Flag of Ukraine

Uppy File Uploader Uppy File Uploader

Uppy is an open source file uploader for web browsers by Transloadit. With over 24,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.

Robodog is an Uppy-based library that helps you talk to the Transloadit API. It includes a modal UI file picker with support for imports from third-party services like Instagram, integration with HTML forms, and more. Because it’s based on Uppy, you can add any existing Uppy plugin to add more functionality.

Transloadit hosts the required server components (Companion and Tusd) for you, as well as of course our encoding API. Robodog configures all the Plugins to leverage this.

If you wonder about the name, Transloadit's encoding features are grouped in Robots :robot: and we advertise Uppy is as cute as a puppy :dog: so we felt Robodog :robot::dog: to be the only appropriate name for a marriage of them.

Install

Option 1: Bundle yourself

npm install @uppy/robodog --save --save-exact

# OR:
yarn add @uppy/robodog

You could then require it via Browserify, Webpack or similar to bundle Uppy yourself like so:

const robodog = require('@uppy/robodog')
require('@uppy/robodog/dist/robodog.css')

This allows you to customize Uppy and create smaller, more focussed bundles leaving out any Plugin you don't need.

Option 2: Use a prebuilt bundle from our CDN

If you don't want to install anything or use bundlers, you can use the prebuilt bundle, by sourcing it directly from our CDN like so:

<link rel="stylesheet" href="//releases.transloadit.com/uppy/robodog/v2.5.1/robodog.min.css">
<script src="//releases.transloadit.com/uppy/robodog/v2.5.1/robodog.min.js"></script>
<!-- you can now use e.g.: window.Robodog.pick() -->

The downside of this is that you cannot just pick a few plugins that you need, and that if our CDN goes down, your file uploader stops working. That said, our CDN is based on AWS CloudFront so this should be unlikely, and if Transloadit itself goes down, file uploading will be broken anyway.

Usage

If you are migrating from the jQuery SDK, we recommend checking out Robodog's migration guide for jQuery SDK. This shows counterparts for all of the old SDKs options, and shows how to create a similar flow, where Uppy would use an existing form to operate on.

But as said, Robodog can also disguise as a button with a modal picker, or draw drag and drop area inline. Uppy is modular and customizable in that regard, and we recommend checking out the full documentation for Uppy's Robodog Plugin to discover the integration best for your use case.

Example

For demo purposes, we'll just show one happy path, of using Transloadit's face detection in combination with a picker, and we'll be using our CDN bundle for easy copy-pastability. Make sure to replace YOUR_TRANSLOADIT_KEY with your Transloadit API Key.

<!-- This pulls Uppy from our CDN. Alternatively use `npm i @uppy/robodog --save` -->
<!-- if you want smaller self-hosted bundles and/or to use modern JavaScript -->
<link href="//releases.transloadit.com/uppy/robodog/v2.5.1/robodog.min.css" rel="stylesheet">
<script src="//releases.transloadit.com/uppy/robodog/v2.5.1/robodog.min.js"></script>
<button id="browse">Select Files</button>
<script>
  document.getElementById('browse').addEventListener('click', function () {
    var uppy = window.Robodog.pick({
      providers: [ 'instagram', 'url', 'webcam', 'dropbox', 'google-drive', 'facebook', 'onedrive' ],
      waitForEncoding: true,
      params: {
        // To avoid tampering, use Signature Authentication
        auth: { key: 'YOUR_TRANSLOADIT_KEY' },
        // To hide your `steps`, use a `template_id` instead
        steps: {
          ':original': {
            robot: '/upload/handle'
          },
          faces_detected: {
            use: ':original',
            robot: '/image/facedetect',
            crop: true,
            crop_padding: '10%',
            faces: 'max-confidence',
            format: 'preserve'
          },
          exported: {
            use: ['faces_detected', ':original'],
            robot: '/s3/store',
            credentials: 'YOUR_AWS_CREDENTIALS',
            url_prefix: 'https://demos.transloadit.com/'
          }
        }
      }
    }).then(function (bundle) {
      // Due to `waitForEncoding: true` this is fired after encoding is done.
      // Alternatively, set `waitForEncoding` to `false` and provide a `notify_url`
      // for Async Mode where your back-end receives the encoding results
      // so that your user can be on their way as soon as the upload completes.
      console.log(bundle.transloadit) // Array of Assembly Statuses
      console.log(bundle.results)     // Array of all encoding results
    }).catch(console.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 Robodog Plugin, which is the recommended way to integrate Transloadit and Uppy.

Related blog posts

Uppy
20% off any plan for the Uppy community
Use the UPPY20 code when upgrading.
Sign up
tus
20% off any plan for the tus community
Use the TUS20 code when upgrading.
Sign up
Product Hunt
20% off any plan for Product Hunters
Use the PRH20 code when upgrading.
Sign up