File & Image Uploader
(With Integrated Cloud Storage)

Get Started — Try on CodePen

Supports: single & multi-file uploads, modal & inline views, localization, mobile, and more...

Installation

Install via NPM:

npm install uploader

Or via YARN:

yarn add uploader

Or via a <script> tag:

<script src="https://js.upload.io/uploader/v1"></script>

Usage

Initialize

Initialize once at the start of your application:

// Ignore if installed via a script tag.
const { Uploader } = require("uploader");

// Get production API keys from Upload.io
const uploader = new Uploader({
  apiKey: "free"
});

Open the Modal

With JavaScript — Try on CodePen:

uploader.open({ multi: true }).then(files => {
  if (files.length === 0) {
    console.log('No files selected.')
  } else {
    console.log('Files uploaded:');
    console.log(files.map(f => f.fileUrl));
  }
}).catch(err => {
  console.error(err);
});

Or with HTML — Try on CodePen:

<button data-upload-config='{ "multi": true }'
        data-upload-complete='alert(
          `Files uploaded:\n${event.files.map(x => x.fileUrl).join("\n")}`
        )'>
  Upload Files...
</button>

Note: you still need to initialize the Uploader when using data-* attributes.

Get the Result

With JavaScript:

.open() returns a promise of UploaderResult[]:

[
  {
    fileUrl: "https://files.upload.io/FW25...",   // The uploaded file URL.
                                                  // This takes the edited file URL first, or if undefined, the original
                                                  // file URL. If an optimization exists for this file type, the URL slug
                                                  // for that file optimization will be appended to the URL.
                                                  // (For images: expect "/thumbnail" to appear at the end of this URL.)

    editedFile: undefined,                        // Undefined or an object with the same structure as 'originalFile' below.
                                                  // The 'editedFile' field is present if image editing is enabled, and
                                                  // references the cropped image.
    originalFile: {
      accountId: "FW251aX",                       // The Upload.io account the file was uploaded to.
      file: { ... },                              // DOM file object (from the <input> element).
      fileId: "FW251aXa9ku...",                   // The uploaded file ID. Append to 'https://files.upload.io/' for the file.
      fileUrl: "https://files.upload.io/FW25...", // The uploaded file URL.
      fileSize: 12345,                            // File size in bytes.
      mime: "image/jpeg",                         // File MIME type.
      tags: [                                     // Tags manually & automatically assigned to this file.
        { name: "tag1", searchable: true },
        { name: "tag2", searchable: true },
        ...
      ]
    }
  },
  ...
]

Or with HTML:

<a data-upload-complete="console.log(JSON.stringify(event.files))">
  Upload a file...
</a>

• The data-upload-complete attribute is fired on completion.
• The event.files array contains the uploaded files.
• The above example opens an Uploader which logs the same output as the JavaScript example.

👀 More Examples

Creating a "Single File" Upload Button

With JavaScript — Try on CodePen:

uploader.open().then(files => alert(JSON.stringify(files)));

Or with HTML — Try on CodePen:

<button data-upload-complete='alert(JSON.stringify(event.files))'>
  Upload a Single File...
</button>

Creating a "Multi File" Upload Button

With JavaScript — Try on CodePen:

uploader.open({ multi: true }).then(files => alert(JSON.stringify(files)));

Or with HTML — Try on CodePen:

<button data-upload-config='{ "multi": true }'
        data-upload-complete='alert(JSON.stringify(event.files))'>
  Upload Multiple Files...
</button>

Creating a Dropzone

You can use Uploader as a dropzone — rather than a modal — by specifying layout: "inline" and a container:

With JavaScript — Try on CodePen:

uploader.open({
  multi: true,
  layout: "inline",
  container: "#example_div_id",  // Replace with the ID of an existing DOM element.
  onUpdate: (files) => console.log(files)
})

Or with HTML — Try on CodePen:

<div data-upload-config='{ "multi": true }'
     data-upload-complete="console.log(event.files)"
     style="position: relative; width: 450px; height: 300px;">
</div>

Note:

• You must set position: relative, width and height on the container div.
• The Finish button is hidden by default in this mode (override with "showFinishButton": true).
• When using the HTML approach:
  • The container & layout: "inline" config options are automatically set.
  • The data-upload-complete callback is fired every time the list of uploaded files changes.
  • The data-upload-finalized callback is fired when Finish is clicked (if visible, see comment above).

🚀 SPA Support

Uploader is SPA-friendly — even when using data-* attributes to render your widgets.

Uploader automatically observes the DOM for changes, making the data-upload-complete attribute safe for SPAs that introduce elements at runtime.

» React Example on CodePen «

🌐 API Support

Uploader is powered by Upload.io's File Upload API — an easy-to-consume API that provides:

• File uploading.
• File listing.
• File deleting.
• File access control.
• File TTL rules / expiring links.
• And more...

Uploading a "Hello World" file is as simple as:

curl --data "Hello World" \
     -u apikey:free \
     -X POST "https://api.upload.io/v1/files/basic"

Note: Remember to set -H "Content-Type: mime/type" when uploading other file types!

Read the File Upload API docs »

⚡ Need a Lightweight Client Library?

Uploader is built on Upload.js — the fast 7KB client library for Upload.io's File Upload API.

Use Upload.js if you have your own file upload UI, and just need to implement file upload functionality.

Upload.js provides:

• End-to-end file upload functionality (zero config — all you need is an Upload API key, e.g. "free".)
• Small 7KB package size (including all dependencies).
• Progress smoothing (using a built-in exponential moving average (EMA) algorithm).
• Automatic file chunking (for large file support).
• Cancellation (for in-progress file uploads).
• And more...

Try Upload.js on CodePen »

⚙️ Configuration

All configuration is optional.

With JavaScript:

uploader
  .open({
    container: "body",           // "body" by default.
    layout: "modal",             // "modal" by default. "inline" also supported.
    locale: myCustomLocale,      // EN_US by default. (See "Localization" section below.)
    maxFileSizeBytes: 1024 ** 2, // Unlimited by default.
    mimeTypes: ["image/jpeg"],   // Unrestricted by default.
    multi: false,                // False by default.
    onUpdate: files => {},       // Called each time the list of uploaded files change.
    showFinishButton: true,      // Whether to show the "finish" button in the widget.
    showRemoveButton: true,      // Whether to show the "remove" button next to each file.
    tags: ["profile_picture"],   // Requires an Upload.io account.
    editor: {
      images: {
        crop: true               // True by default.
      }
    },
  })
  .then(files => alert(files))

Or with HTML:

<button data-upload-complete='alert(event.files)'
        data-upload-config='{
          "container": "body",
          "layout": "modal",
          "multi": false
        }'>
  Upload a File...
</button>

🏳️ Localization

Default is EN_US:

const myCustomLocale = {
  "addAnotherFile":      "Add another file...",
  "cancel":              "cancel",
  "cancelled!":          "cancelled",
  "finish":              "Finished",
  "finishIcon":          true,
  "maxSize":             "Max size:",
  "orDragDropFile":      "...or drag and drop a file.",
  "orDragDropFiles":     "...or drag and drop files.",
  "pleaseWait":          "Please wait...",
  "removed!":            "removed",
  "remove":              "remove",
  "unsupportedFileType": "File type not supported.",
  "uploadFile":          "Select a File",
  "uploadFiles":         "Select Files"
}

📷 Resizing & Cropping Images

Given an uploaded image URL:

https://files.upload.io/W142hJkHhVSQ5ZQ5bfqvanQ

Resize with:

https://files.upload.io/W142hJkHhVSQ5ZQ5bfqvanQ/thumbnail

Auto-crop with:

https://files.upload.io/W142hJkHhVSQ5ZQ5bfqvanQ/thumbnail-square

🎯 Features

Uploader is the file & image upload widget for Upload.io: the file upload service for developers.

Core features (available without an account):

• Beautifully clean UI widget.
• Lightweight. (29KB gzipped including all dependencies — see Upload.js for an ultra-lightweight solution.)
• Single & Multi-File Uploads.
• Fluid Layout & Mobile-Friendly.
• Modal & Inline Modes.
• Localization.
• Integrated File Hosting:
  • Files stored on Upload.io for 4 hours with the "free" API key.
  • Files hosted via the Upload CDN: 100 locations worldwide.
• Image Transformations:
  • Append /thumbnail or /thumbnail-square to your image URLs.
  • Get more transformations with a full account.

All features (available with an account):

• Permanent Storage.
• Unlimited Daily Uploads. (The "free" API key allows 100 uploads per day per IP.)
• Extended CDN Coverage. (Files served from 300+ locations worldwide.)
• Upload & Download Authentication. (Supports federated auth via your own JWT authorizer.)
• File & Folder Management Console.
• Expiring Links.
• Custom CNAME.
• Advanced Upload Control:
  • Rate Limiting.
  • Traffic Limiting.
  • File Size Limiting.
  • IP Blacklisting.
  • File Type Blacklisting.
  • And More...

Create an Upload.io account »

Contribute

If you would like to contribute to Uploader:

1. Add a GitHub Star to the project (if you're feeling generous!).
2. Determine whether you're raising a bug, feature request or question.
3. Raise your issue or PR.

License

MIT