# upup

upup is an MIT-licensed, self-hosted file uploader: one headless core plus
native, DOM-identical UI packages for React, Vue, Svelte, Angular, Vanilla JS,
and Preact, with optional server-mode uploads and cloud-drive sources.

## Docs

- [Use upup with AI assistants](https://useupup.com/docs/ai-assistants/): How coding agents (Claude Code, Cursor, and others) discover and correctly integrate upup — machine-readable context files and a paste-ready context block.
- [Azure SAS Responses](https://useupup.com/docs/api-reference/azure-generate-sas-url/): Return an Azure Blob SAS URL shaped as upup's presign contract so the browser can PUT directly to blob storage in client mode.
- [Error Codes](https://useupup.com/docs/api-reference/error-codes/): The complete UpupErrorCode enum, the seven UpupError classes that carry them, restriction reasons, and the parser that turns error bodies into typed errors.
- [File Upload Events](https://useupup.com/docs/api-reference/events/): The complete upup event catalog — all 52 typed core events with their payloads, plus the React callback props and the core event each one is driven by.
- [S3 Presign Responses](https://useupup.com/docs/api-reference/s3-generate-presigned-url/): The PresignedUrlResponse shape your client-mode presign endpoint returns so upup can upload bytes directly to S3.
- [Server HTTP API](https://useupup.com/docs/api-reference/server-http/): The complete HTTP contract of @useupup/server — every route, request and response shape, status code and header, for custom clients and live debugging.
- [Theme Slots](https://useupup.com/docs/api-reference/upupuploader/classnames/): The stable per-element styling API — theme.slots keyed by component then slot, plus theme.mode for the color scheme.
- [Event Handlers](https://useupup.com/docs/api-reference/upupuploader/event-handlers/): The UpupUploader callback props — onFilesSelected, onUploadStart, progress, per-file and batch completion, onFileRemoved and onError — mirroring core state.
- [Icon Prop](https://useupup.com/docs/api-reference/upupuploader/icon-prop/): Override the UpupUploader's built-in icons — camera, delete, rotate, add-more, and loader — with any React component that accepts a className.
- [Image Editor](https://useupup.com/docs/api-reference/upupuploader/image-editor/): Enable in-uploader cropping, annotation, filters, and watermarking with the imageEditor prop — available in the React and Preact packages only.
- [Optional Props](https://useupup.com/docs/api-reference/upupuploader/optional-props/): The complete optional-prop reference for UpupUploader — behavior, file validation, the processing pipeline, upload reliability, sources, appearance and i18n.
- [Ref API](https://useupup.com/docs/api-reference/upupuploader/ref-api/): The UploaderRef imperative surface — a useUpload() accessor exposing files, progress, and the upload, uploadFiles, setFiles, and replaceFiles commands.
- [Required Props](https://useupup.com/docs/api-reference/upupuploader/required-props/): UpupUploader runs with no upload target as a local file collector; for real uploads, configure exactly one of uploadEndpoint, serverUrl, or resumable.endpoint.
- [Code Examples](https://useupup.com/docs/code-examples/): Ready-to-copy upup snippets — source pickers, client-mode uploads, a presign endpoint handler, and server-mode wiring.
- [upup vs FilePond](https://useupup.com/docs/comparisons/upup-vs-filepond/): An honest, factual comparison of upup and FilePond — a polished, accessible file uploader with first-party framework adapters — to help you choose.
- [upup vs react-dropzone](https://useupup.com/docs/comparisons/upup-vs-react-dropzone/): An honest, factual comparison of upup and react-dropzone — a headless drag-and-drop primitive versus a full file uploader — so you can pick the right scope.
- [upup vs UploadThing — Self-Hosted Alternative](https://useupup.com/docs/comparisons/upup-vs-uploadthing/): A factual upup vs UploadThing comparison — a free, MIT-licensed uploader you self-host against your own S3 bucket versus a managed, hosted upload service.
- [upup vs Uppy — Which Uploader to Choose](https://useupup.com/docs/comparisons/upup-vs-uppy/): A factual upup vs Uppy comparison — two free, MIT-licensed file uploaders with headless cores, cloud drives and resumable uploads, and where they differ.
- [Credentials and CORS](https://useupup.com/docs/credentials-configuration/): Keep storage keys and OAuth client secrets in server mode; configure your bucket's CORS policy for browser direct uploads.
- [Error Handling](https://useupup.com/docs/error-handling/): upup reports failures as a typed UpupError taxonomy with stable codes — narrow by instanceof or error code, and configure automatic or manual retries.
- [Getting Started](https://useupup.com/docs/getting-started/): Install upup and run your first upload — local file selection, client uploads straight to your storage, or full server mode with @useupup/server.
- [Accessibility](https://useupup.com/docs/guides/accessibility/): What upup ships by default — keyboard interaction, ARIA roles and live regions, focus management on overlays, and prefers-reduced-motion handling.
- [Auth Recipes](https://useupup.com/docs/guides/auth-recipes/): Wire your existing auth into @useupup/server — one getUserId hook, recipes for Better Auth, NextAuth, Clerk and raw JWT, plus Redis and SQL TokenStores.
- [Authenticate uploads with Better Auth](https://useupup.com/docs/guides/auth/better-auth/): Wire a Better Auth session into @useupup/server so every upload is scoped to the signed-in user — the getUserId hook, gated sessions, uid binding.
- [Authenticate uploads with Clerk](https://useupup.com/docs/guides/auth/clerk/): Scope S3 uploads to the Clerk user — authenticateRequest inside @useupup/server's getUserId hook, why authorizedParties is mandatory, and multipart uid binding.
- [Authenticate uploads with a custom JWT](https://useupup.com/docs/guides/auth/custom-jwt/): Verify your own JWT inside @useupup/server's getUserId hook with jose — bearer or cookie, shared secrets, and remote JWKS for asymmetric tokens.
- [Authenticate uploads with NextAuth (Auth.js v5)](https://useupup.com/docs/guides/auth/next-auth/): Scope @useupup/server uploads to the NextAuth session — the auth() helper in the App Router, getToken outside a request, and the missing session.user.id.
- [Error Monitoring](https://useupup.com/docs/guides/error-monitoring/): Wire upup's structured errors — upload-error events, UpupError codes, and the server onError seam — into your error tracker.
- [File Processing](https://useupup.com/docs/guides/file-processing/): upup client-side pipeline — image compression, HEIC to JPEG conversion, EXIF stripping, thumbnails, SHA-256 checksums, Web Worker offload and custom steps.
- [Headless Usage](https://useupup.com/docs/guides/headless/): Build your own uploader UI on the upup engine — the useUpupUpload React hook, driving UpupCore directly, and the webWorker, HEIC and resumable opt-ins.
- [Client Mode vs Server Mode](https://useupup.com/docs/guides/modes/): Choose between client mode (your presign endpoint) and server mode (@useupup/server proxies uploads) — what runs where and when to pick each.
- [Plugins & Extensions](https://useupup.com/docs/guides/plugins/): Enable upup's built-in cloud-drive plugins with the cloudDrives config, compare client- and server-mode drives, and register third-party plugins on UpupCore.
- [Client-side image compression before upload](https://useupup.com/docs/guides/processing/compression/): Compress and resize images in the browser before they upload — quality, maxWidthOrHeight and maxSizeMB options, the size-target backoff, and output formats.
- [Custom file processing pipeline steps](https://useupup.com/docs/guides/processing/custom-steps/): Write your own upup PipelineStep — the contract, safe UploadFile cloning, registering a custom pipeline, and Web Worker offload with main-thread fallback.
- [Convert HEIC to JPEG in the browser](https://useupup.com/docs/guides/processing/heic-conversion/): Convert iPhone HEIC/HEIF photos to JPEG before upload with upup — install the optional libheif decoder, matching rules, and failure behavior.
- [Reliability](https://useupup.com/docs/guides/reliability/): How upup survives flaky networks — the per-file retry policy and its backoff math, custom success predicates, upload concurrency, and multipart resume.
- [File upload server with Express and S3](https://useupup.com/docs/guides/server-adapters/express/): Mount @useupup/server on an Express route with createUpupMiddleware — install, config, the express.json() ordering trap, proxy origins, and CORS.
- [File upload server with Fastify and S3](https://useupup.com/docs/guides/server-adapters/fastify/): Register @useupup/server as a Fastify plugin with createUpupPlugin — install, the mount-path option, body parsing, trustProxy origins, and CORS.
- [File upload server with Hono and S3](https://useupup.com/docs/guides/server-adapters/hono/): Wire @useupup/server into Hono with createUpupRoutes — the web-native mount, no body parsing, edge-runtime bindings, and CORS.
- [File upload server with Next.js and S3](https://useupup.com/docs/guides/server-adapters/nextjs/): Mount @useupup/server in Next.js — App Router via createUpupNextHandler, Pages Router via createUpupPagesHandler, plus proxy origins, bodyParser, and CORS.
- [Server Auth & Trust Model](https://useupup.com/docs/guides/server-auth/): How @useupup/server authenticates uploads — the mandatory HMAC upload-token secret, the secure-by-default 403 on anonymous uploads, and per-user scoping.
- [Server Mode Setup — Upload Through Your Server](https://useupup.com/docs/guides/server-mode-setup/): Set up upup server mode — mount createUpupHandler, configure S3 storage, secrets, limits and hooks, then pick an Express, Fastify, Hono or Next.js adapter.
- [Upload Sources](https://useupup.com/docs/guides/sources/): Every input the uploader ships — local files, drag and drop, paste, folder upload, camera, microphone, screen capture, URL import, and cloud drives.
- [Storage Providers](https://useupup.com/docs/guides/storage-providers/): Connect upup to any S3-compatible storage — AWS S3, Cloudflare R2, MinIO, Backblaze B2, DigitalOcean Spaces, Wasabi and more, with a guide per provider.
- [Upload files to Amazon S3](https://useupup.com/docs/guides/storage/aws-s3/): Upload files to AWS S3 from React, Vue, Svelte, Angular, or plain JS with upup — bucket setup, IAM policy, CORS, and a copy-paste createUpupHandler config.
- [Upload Files to Azure Blob Storage with a SAS URL](https://useupup.com/docs/guides/storage/azure-blob/): Upload files to Azure Blob Storage from the browser with upup — a server-issued SAS URL, the mandatory x-ms-blob-type PUT header, no account key in the client.
- [Upload files to Backblaze B2](https://useupup.com/docs/guides/storage/backblaze-b2/): Upload files to Backblaze B2 from React, Vue, Svelte, or plain JS with upup — application keys, the region-scoped S3 endpoint, CORS, and a copy-paste config.
- [Upload Files to Cloudflare R2 from the Browser](https://useupup.com/docs/guides/storage/cloudflare-r2/): Upload files to Cloudflare R2 with upup — the account-scoped endpoint, region auto, API tokens, CORS, and a copy-paste React, Vue or plain JS config.
- [Upload Files to DigitalOcean Spaces from the Browser](https://useupup.com/docs/guides/storage/digitalocean-spaces/): Upload files to DigitalOcean Spaces with upup — Spaces access keys, the regional S3 endpoint, CORS, the CDN, and a copy-paste React, Vue or plain JS config.
- [Upload Files to MinIO from the Browser](https://useupup.com/docs/guides/storage/minio/): Upload files to a self-hosted MinIO server with upup — Docker setup, path-style addressing, CORS, and a copy-paste React, Vue, Svelte or plain JS config.
- [Upload files to any S3-compatible storage](https://useupup.com/docs/guides/storage/s3-compatible/): Upload files to Wasabi, Google Cloud Storage, Supabase, Hetzner, Scaleway, Storj, and any other S3-compatible store from React, Vue, or plain JS with upup.
- [Theming](https://useupup.com/docs/guides/theming/): Style the upup uploader with the theme prop — light, dark and system modes, design tokens as CSS variables, slot class overrides, and data-upup-slot hooks.
- [Write a custom upup plugin](https://useupup.com/docs/guides/writing-plugins/): Build a custom upload-source plugin for upup — the UpupPlugin contract, namespaced events, registering with core.use(), and subclassing PopupOAuthPlugin.
- [File Uploader Documentation](https://useupup.com/docs/): Docs for upup, the free and open-source file uploader with native UI for React, Vue, Svelte, Angular, Vanilla JS and Preact, plus an optional server mode.
- [Localization (i18n)](https://useupup.com/docs/localization/): upup ships nine ICU locale bundles from @useupup/core/i18n — set the locale on any framework uploader, override message keys, and get RTL and plurals.
- [Migrating from v1 to v3](https://useupup.com/docs/migration/v1-to-v3/): Upgrade from upup v1 (upup-react-file-uploader) to v3 — the rename to @useupup/react, the v1 to v3 prop map, the error taxonomy, and client vs server mode.
- [Angular Quickstart](https://useupup.com/docs/quickstarts/angular/): Add a file uploader to an Angular 19+ app with @useupup/angular — a standalone component, drag and drop, cloud drives, camera, and resumable uploads.
- [Next.js Quickstart](https://useupup.com/docs/quickstarts/next/): Add a file uploader to a Next.js app with @useupup/next — client UI and server handlers in one install, split so the AWS SDK never reaches your bundle.
- [Preact Quickstart](https://useupup.com/docs/quickstarts/preact/): Add a file uploader to a Preact app with @useupup/preact — a preact/compat re-export of @useupup/react, drag and drop, cloud drives, and resumable uploads.
- [React Quickstart](https://useupup.com/docs/quickstarts/react/): Add a file uploader to a React 19 app with @useupup/react — one npm install, drag and drop, cloud drives, camera, and resumable uploads, no server to run.
- [Svelte Quickstart](https://useupup.com/docs/quickstarts/svelte/): Add a file uploader to a Svelte 5 app with @useupup/svelte — one npm install, drag and drop, cloud drives, camera, and resumable uploads to any S3 storage.
- [Vanilla JS Quickstart](https://useupup.com/docs/quickstarts/vanilla/): Add a file uploader to any page with @useupup/vanilla — framework-free, drag and drop, cloud drives, camera, and resumable uploads to any S3 storage.
- [Vue Quickstart](https://useupup.com/docs/quickstarts/vue/): Add a file uploader to a Vue 3 app with @useupup/vue — one npm install, drag and drop, cloud drives, camera, and resumable uploads to any S3 storage.
- [Resumable Uploads — S3 Multipart & tus](https://useupup.com/docs/resumable-uploads/): Resumable file uploads in upup — S3 multipart through @useupup/server or the tus protocol, with part-size rules and what each protocol actually resumes.