Sleek, modular and open source. Pulls files from disk, Dropbox or Drive, and resumes if the connection drops.
# Add Uppy File Uploader
Set up Uppy (v5) by following the official integration guide for this project's framework, then wire up an uploader backend.
## Step 1: Detect the framework
Read `package.json` and match against this table:
| Dependency | Integration guide |
|------------|-------------------|
| `next` | https://uppy.io/docs/nextjs/ |
| `react-router` / `@react-router/dev` / `@remix-run/react` | https://uppy.io/docs/reactrouter/ |
| `@sveltejs/kit` | https://uppy.io/docs/sveltekit/ |
| `react` (no meta-framework) | https://uppy.io/docs/react/ |
| `vue` | https://uppy.io/docs/vue/ |
| `svelte` | https://uppy.io/docs/svelte/ |
| `@angular/core` | https://uppy.io/docs/angular/ |
| none (vanilla JS/HTML) | https://uppy.io/docs/quick-start/ |
Nuxt, Astro, and other meta-frameworks have no dedicated page — use the underlying framework's guide and mount Uppy client-side only.
## Step 2: Choose the uploader
This is the decision that shapes everything else. Ask the user if it isn't obvious from the codebase.
| Situation | Plugin | Docs |
|-----------|--------|------|
| Managed uploads + encoding/processing, no server to run | `@uppy/transloadit` | https://uppy.io/docs/transloadit/ |
| Resumable uploads to your own tus server | `@uppy/tus` | https://uppy.io/docs/tus/ |
| Direct to S3 or S3-compatible storage | `@uppy/aws-s3` | https://uppy.io/docs/aws-s3/ |
| Plain POST/PUT to an existing endpoint | `@uppy/xhr-upload` | https://uppy.io/docs/xhr-upload/ |
Full reasoning: https://uppy.io/docs/guides/choosing-uploader/
## Step 3: Install and wire up
```bash
npm install @uppy/core @uppy/dashboard @uppy/react # swap @uppy/react for @uppy/vue / @uppy/svelte / @uppy/angular
npm install @uppy/tus # + the uploader chosen in step 2
```
Minimal React/Next.js shape:
```tsx
'use client';
import { useState } from 'react';
import Uppy from '@uppy/core';
import Dashboard from '@uppy/react/dashboard';
import Tus from '@uppy/tus';
import '@uppy/core/css/style.min.css';
import '@uppy/dashboard/css/style.min.css';
function createUppy() {
return new Uppy().use(Tus, { endpoint: '/api/upload' });
}
export function Uploader() {
const [uppy] = useState(createUppy);
return <Dashboard uppy={uppy} />;
}
```
Then implement the server side for whichever uploader was chosen (tus handler, S3 signing route, or plain upload endpoint). Follow the framework guide — it has the server code for that specific router.
## Step 4: Remote sources (only if asked for)
Google Drive, Dropbox, OneDrive, Box, Unsplash, and import-from-URL require Companion, a server-side component.
- Quick path: `@uppy/remote-sources` pointed at Transloadit's hosted Companion
- Self-hosted: https://uppy.io/docs/companion/
- Companion 6 requires `corsOrigin` to be set explicitly — it will not start sensibly without it
## Step 5: Custom UI (only if the Dashboard doesn't fit)
Uppy 5 ships headless components and hooks. Prefer these over building from scratch:
```tsx
import { UppyContextProvider, Dropzone, FilesList, UploadButton } from '@uppy/react';
```
Or drop to hooks — `useDropzone`, `useUppyState`, `useUppyEvent` — and render your own markup. Equivalents exist for Vue and Svelte.
## Critical rules
- **CSS paths changed in v5**: `@uppy/core/css/style.min.css`, not `@uppy/core/dist/css/style.min.css`
- **Component imports are subpaths now**: `import Dashboard from '@uppy/react/dashboard'`, not `import { Dashboard } from '@uppy/react'`
- **Never construct Uppy in a render body.** React: `const [uppy] = useState(createUppy)`. Recreating the instance on every render is the single most common Uppy bug.
- **Uppy is client-only.** `'use client'` in Next.js App Router; no SSR of the Dashboard.
- `new Uppy()` — the export is not callable as a function
- **Removed/deprecated in v5**: `@uppy/status-bar` and `@uppy/informer` merged into `@uppy/dashboard` (move their options onto Dashboard); `@uppy/progress-bar`, `@uppy/drag-drop`, `@uppy/file-input` deprecated in favour of headless components and hooks
- `@uppy/aws-s3-multipart` no longer exists — use `@uppy/aws-s3` with `shouldUseMultipart`
- **Never put a Transloadit auth secret in client code.** Use `assemblyOptions()` as an async function that fetches a signature from your own server; it runs once per upload batch, not per file.
- To change plugin options after mount, use `uppy.setOptions()` / `uppy.getPlugin('Webcam').setOptions()` inside an effect — don't rebuild the instance
- The CDN bundle (`releases.transloadit.com/uppy/...`) contains nearly every plugin — fine for a prototype, not for production
Docs index: https://uppy.io/docs/quick-start/
Breaking changes: https://uppy.io/docs/guides/migration-guides/
Runnable examples: https://github.com/transloadit/uppy/tree/main/examples
Need to resize, encode, optimize, store or deliver your files?
Companion is a hosted, standalone or middleware server that takes away the complexity of authentication and the cost of downloading files from remote sources. A 5 GB video never touches your user’s data plan, and you never touch an OAuth flow.
Large uploads survive network hiccups, thanks to the open Tus standard.
Crash recovery
Files come back after a browser crash or an accidental navigation, via Golden Retriever.
Hand off to Transloadit
Send files straight to Transloadit for encoding and file processing.
Drag and drop
Built into the Dashboard, or take DragDrop on its own — and DropTarget makes any element a drop zone.
Edit before uploading
Crop, rotate and resize in the browser with the Image Editor, and shrink files with Compressor.
Ships in 40 locales
Drop in a locale pack, or override single strings to match your own copy.
Modular by design
Every part is a plugin, all of them included — there is no paid edition. Take the whole Dashboard, or wire up only the pieces you need.
No build step needed
Load Uppy from the CDN with a <script> tag and skip the bundler entirely.
Accessible by default
Keyboard navigation and screen readers are designed for, not bolted on.
Who makes Uppy
Made by Transloadit
Uppy is the open-source file uploader created and maintained by Transloadit. We originally built it to solve browser-upload problems reported by Transloadit customers, then released it under the MIT License for everyone to use. Uppy works with many upload backends; with Transloadit, it is the official browser uploader and provides first-party support for resumable uploads, remote sources, and Assembly progress.
Upload
ResizeEncodeDeliver
Uppy uploads a file from the browser, then hands it to Transloadit, which resizes, encodes and delivers it in the cloud.
Start uploading in a minute
One npm install, one plugin, and files are moving.
ResizeEncodeDeliver