Uppy File Uploader

Uppy is an open source file uploader for web browsers by Transloadit. With over 30,000 stargazers on GitHub it is the #1 file uploader in the world. Uploads can survive network hiccups, browser crashes, and accidental navigate-aways thanks to tus support built-in, and it is the recommended way to integrate Transloadit with web browsers.

The Transloadit plugin for Uppy helps you talk to the Transloadit API. It can be used with all the other Uppy plugins, for example the modal UI file picker with support for imports from third-party services like Instagram, integration with HTML forms, and more.

Transloadit hosts tusd for resumable uploads and our encoding API. When you add remote sources, we also host Companion for you.

Uploading with Uppy + Transloadit

Think of Uppy as the browser upload UX and Transloadit as the processing pipeline:

Uppy collects files (local, camera, or remote sources) and uploads them with tus resumability.
Transloadit executes your Assembly (encode, optimize, analyze, store, etc.).
Delivery happens from your storage, optionally through your CDN or Transloadit's CDN (TLCDN).

If you only need uploads and storage, you can keep your Assembly minimal (just /upload/handle and an export step). If you need transformations, add the relevant Robots and keep the upload UX the same—Uppy doesn’t change.

This makes it easy to offer a single, consistent upload UI while switching out or extending the processing steps as your product evolves.

Framework guides

Start with the canonical Uppy guide for the Template and server-signing setup, then jump to the client section for your stack:

The guide keeps the Transloadit Auth Secret on your server, signs short-lived Assembly options, and gives the browser only the values required by @uppy/transloadit. Your server should choose the allowed Template and authorize the current user before signing; it should not sign arbitrary Instructions supplied by the browser.

Example

For demo purposes, we'll show one happy path using Transloadit's face detection with a picker and our CDN bundle. This copy-paste demo deliberately places an Auth Key and unsigned Instructions in the browser. Use it only with test credentials. For production, use the server-signed Template flow in the framework guide above.

<!-- TEST/DEMO ONLY: uses test credentials and unsigned Instructions in the browser. -->
<!-- For production, use https://uppy.io/docs/guides/uppy-transloadit/ -->
<!-- This pulls Uppy from our CDN -->
<!-- For smaller self-hosted bundles, install Uppy and plugins manually: -->
<!-- npm i @uppy/core @uppy/dashboard @uppy/image-editor @uppy/remote-sources @uppy/transloadit -->
<link href="https://releases.transloadit.com/uppy/v5.2.4/uppy.min.css" rel="stylesheet" />
<button id="browse">Select Files</button>
<script type="module">
  import {
    Uppy,
    Dashboard,
    ImageEditor,
    RemoteSources,
    Transloadit,
  } from 'https://releases.transloadit.com/uppy/v5.2.4/uppy.min.mjs'
  const uppy = new Uppy()
    .use(Transloadit, {
      waitForEncoding: true,
      alwaysRunAssembly: true,
      assemblyOptions: {
        params: {
          // To avoid tampering, use Signature Authentication:
          // https://transloadit.com/docs/api/authentication/
          auth: {
            key: 'YOUR_TRANSLOADIT_KEY',
          },
          // It's often better to store encoding instructions in your account
          // and use a template_id instead of adding these steps inline
          steps: {
            ':original': {
              robot: '/upload/handle',
            },
            faces_detected: {
              use: ':original',
              robot: '/image/facedetect',
              crop: true,
              faces: 'max-confidence',
              format: 'preserve',
              crop_padding: '10%',
            },
            exported: {
              use: ['faces_detected', ':original'],
              robot: '/s3/store',
              credentials: 'demo_s3_credentials',
              url_prefix: 'https://demos.transloadit.com/',
            },
          },
        },
      },
    })
    .use(Dashboard, { trigger: '#browse' })
    .use(ImageEditor, { target: Dashboard })
    // Optional: only needed for remote sources. Local-device uploads do not need Companion.
    .use(RemoteSources, {
      companionUrl: 'https://api2.transloadit.com/companion',
    })
    .on('complete', ({ transloadit }) => {
      // Due to waitForEncoding:true this is fired after encoding is done.
      // Alternatively, set waitForEncoding to false and provide a notify_url
      console.log(transloadit) // Array of Assembly Statuses
      transloadit.forEach((assembly) => {
        console.log(assembly.results) // Object of encoding results keyed by Step name
      })
    })
    .on('error', (error) => {
      console.error(error)
    })
</script>

For more examples, take a look at examples/, or try them live. Uppy and Transloadit are very versatile so you may have a different need, and likely, we already support it.

Documentation

See the full documentation for Uppy's Transloadit Plugin, which is the complete plugin API. Start with the framework guide for an end-to-end integration.