Guide · Open source

How to use Uppy: install, set up uploads and tips

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Uppy is an open source JavaScript file uploader that adds an upload interface to a web page or app. This guide explains what it is, how to install the packages you need, and how to set up a basic upload with the Dashboard and the tus destination. By the end you will know which optional pieces to add for cloud imports and resumable uploads.

Uppytransloadit/uppy · ★ 31.1k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure you have Node.js and npm, or a bundler, if you use the npm route.
2Install the packages. Run npm install @uppy/core @uppy/dashboard @uppy/tus in your project.
3Add the CSS. Include uppy.min.css in your page head or import it through your bundler.
4Create the Uppy instance. Create a new Uppy object and attach the Dashboard with a target element.
5Attach a destination. Use the Tus plugin with an endpoint URL to receive resumable uploads.
6Listen for completion. Subscribe to the complete event to handle finished uploads.
7Add optional sources. For Google Drive, Dropbox or Box imports, set up @uppy/companion on a server.

What Uppy is and who it is for

Uppy is a modular file uploader for web browsers, written in TypeScript and released under the MIT licence. You install only the plugins you need, such as a drag-and-drop dashboard, a webcam option, or a destination like tus or AWS S3.

It suits web developers who need a ready-made upload interface, teams that want resumable uploads for large files, and projects built with React, Svelte, Vue, or plain JavaScript. It is a library you embed in your own product, not a finished end-user app.

Good fit: adding uploads to your own app with a ready-made interface.
Good fit: resumable uploads for large files via the tus standard.
Not a fit: a simple page that only needs a basic HTML file input, which the README notes may be enough in many cases.

Install Uppy with npm

You need Node.js and npm, or a bundler, for the npm install route. Install the core, Dashboard, and tus packages with the command below.

npm install @uppy/core @uppy/dashboard @uppy/tus

Add the CSS and create an Uppy instance

Add the Uppy stylesheet, uppy.min.css, either in your HTML page's head or imported into JavaScript if your bundler supports it. Then create an Uppy instance and attach plugins with use(). The Dashboard plugin needs a target element on the page, and Tus needs an endpoint.

The example below uses the public demo endpoint from the README. Replace it with your own upload server URL in a real project.

<link href="https://releases.transloadit.com/uppy/v6.0.5/uppy.min.css" rel="stylesheet" />
<div id="files-drag-drop"></div>
<script type="module">
  import { Uppy, Dashboard, Tus } from 'https://releases.transloadit.com/uppy/v6.0.5/uppy.min.mjs'

  const uppy = new Uppy()
  uppy.use(Dashboard, { target: '#files-drag-drop' })
  uppy.use(Tus, { endpoint: 'https://tusd.tusdemo.net/files/' })
</script>

Add cloud imports and other sources

Uppy can fetch files from local disk, remote URLs, Google Drive, Dropbox, Box, and a webcam. Google Drive, Dropbox, Box, Facebook, OneDrive, and Import From URL are marked in the README as needing @uppy/companion, a server-side component. Without a running Companion instance, those plugins will not work.

The Dashboard is required for most UI plugins, such as Webcam. The README example adds RemoteSources, Webcam, and ImageEditor alongside Dashboard and Tus.

Webcam: snap photos or record video directly in the browser.
Google Drive, Dropbox, Box, OneDrive, Facebook, Import From URL: need @uppy/companion running on a server.
Drag & Drop and File Input: plain sources that need no server component.

Listen for upload results

Uppy emits events you can listen to. The README example logs the result when the 'complete' event fires, which lets you act on finished uploads in your own code.

uppy.on('complete', (result) => {
  console.log('Upload result:', result)
})

Choose a destination and optional processing

Pick where files go. Tus gives resumable uploads via the open tus standard, so large uploads survive network hiccups. XHR Upload works with any regular backend, such as Apache or Nginx. AWS S3 handles plain uploads to S3 or compatible services.

Uppy can also hand files to Transloadit for encoding and processing, or you can run your own pipeline. Optional Golden Retriever restores files after a browser crash.

Tus: resumable uploads.
XHR Upload: regular uploads to any backend.
AWS S3: plain upload to AWS S3 or compatible services.
Transloadit: creates Assemblies for encoding and processing.

What people use it for

Adding a drag-and-drop upload area with previews and progress bars to a web app.
Letting users upload large files that resume after network interruptions via tus.
Importing files from Google Drive or Dropbox into a product, with Companion running on your server.
Capturing selfies or video from a webcam directly into an upload form.
Building a custom upload UI with headless components or hooks in React, Svelte, or Vue.

Frequently asked questions

Is Uppy free to use?

Yes. The README describes Uppy as free for the world, forever, and the repository is released under the MIT licence. Check the LICENSE file in the repository for the full terms.

What do I need to install Uppy?

For the npm install route you need Node.js and npm, or a bundler. Install the core, Dashboard, and tus packages with npm install @uppy/core @uppy/dashboard @uppy/tus.

Do I need a server to use Uppy?

Not for basic uploads. Google Drive, Dropbox, Box, Facebook, OneDrive, and Import From URL need @uppy/companion, a server-side component, to work.

Is Uppy a finished app for end users?

No. The project describes Uppy as a library to embed in your own product, not a finished end-user application.

Which frameworks does Uppy support?

The README says Uppy has first-class support for plain JavaScript and HTML, React, Svelte, Vue, and Angular. For supported frameworks except Angular, it offers pre-composed components, headless components, and hooks.

What are alternatives to Uppy?

The project lists Dropzone, FilePond, Fine Uploader, and Resumable.js as comparable projects. Compare them against your needs for resumable uploads, cloud imports, and UI customisation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Uppy suits web developers who want a ready-made, customisable upload interface, resumable uploads via tus, or cloud imports, and who can run a server component if they need Google Drive or Dropbox. If you only need a basic HTML file input, or you want a finished end-user app, pick a simpler option instead.

Install options & downloads