Uppy — Modular JavaScript File Uploader

Introduction

Uppy is an open-source file uploader built by Transloadit. Its plugin architecture lets you compose a custom upload experience from modular pieces: a dashboard UI, import sources like Google Drive or Dropbox, webcam capture, image editing, and resumable uploads over tus or multipart HTTP.

What Uppy Does

• Provides a polished drag-and-drop upload UI with progress bars and file previews
• Imports files from local disk, webcam, URLs, Google Drive, Dropbox, Instagram, and more
• Supports resumable uploads via the tus protocol so large files survive network interruptions
• Offers image cropping and editing before upload via the Image Editor plugin
• Enforces file restrictions on type, size, and count before upload begins

Architecture Overview

Uppy follows a core-plus-plugins design. The core (@uppy/core) manages the file list, state machine, and event bus. UI plugins like Dashboard and DragDrop render the interface. Uploader plugins (Tus, XHR Upload, AWS S3) handle the transport layer. Provider plugins (Google Drive, Dropbox) connect to remote file sources through Companion, a server-side proxy that handles OAuth and streams files directly to the destination.

Self-Hosting & Configuration

• Install individual packages via npm: @uppy/core, @uppy/dashboard, and your chosen uploader
• Configure file restrictions with restrictions: { maxFileSize, allowedFileTypes, maxNumberOfFiles }
• Deploy the Companion server for remote sources: npx @uppy/companion or via Docker
• Set Companion environment variables for OAuth credentials per provider
• Enable resumable uploads by pointing the Tus plugin at a tus-compatible server endpoint

Key Features

• Plugin-based: include only the pieces you need to keep bundle size small
• Companion server proxies remote files without routing them through the browser
• Golden Retriever plugin recovers uploads after browser crashes using IndexedDB and Service Workers
• Framework integrations for React, Vue, Angular, and Svelte
• Locale packs for 30+ languages with full RTL support

Comparison with Similar Tools

• Dropzone.js — Simpler API but no remote sources, no resumable uploads, no plugin ecosystem
• FilePond — Beautiful UI with good defaults; fewer remote source integrations than Uppy
• Fine Uploader — Mature but no longer maintained; Uppy is actively developed
• react-dropzone — Lightweight React hook for drop zones; Uppy provides a full upload pipeline
• tus-js-client — Low-level tus client; Uppy wraps it with UI, state management, and plugins

FAQ

Q: Does Uppy require a specific backend? A: No. Uppy works with any HTTP endpoint via the XHR Upload plugin. For resumable uploads, you need a tus-compatible server like tusd.

Q: What is Companion and when do I need it? A: Companion is a Node.js server that handles OAuth and proxies files from remote sources (Google Drive, Dropbox) to your storage. You only need it if you use remote provider plugins.

Q: Can I customize the Uppy UI? A: Yes. Override the Dashboard CSS variables, use the headless mode with the DragDrop or FileInput plugins, or build a custom UI using Uppy's state and event API.

Q: Is Uppy free? A: Yes. Uppy is MIT-licensed. Transloadit offers an optional paid encoding and processing service that integrates via a plugin.

Sources

• https://github.com/transloadit/uppy
• https://uppy.io/docs/