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 Promise<Array<UploaderResult>>:

{
  fileUrl: "https://files.upload.io/FW25...",  // The URL to use when serving this file.

  editedFile: undefined,                       // The edited file (if present). Same as below.

  originalFile: {
    accountId: "FW251aX",                       // The Upload.io account that owns the file.
    file: { ... },                              // DOM file object (from the <input> element).
    fileId: "FW251aXa9ku...",                   // The uploaded file ID.
    fileUrl: "https://files.upload.io/FW25...", // The uploaded file URL.
    fileSize: 12345,                            // File size in bytes.
    mime: "image/jpeg",                         // File MIME type.
    suggestedOptimization: {
      transformationUrl: "https://files.up...", // The suggested URL for serving this file.
      transformationSlug: "thumbnail"           // Append to 'fileUrl' to produce the above URL.
    },
    tags: [                                     // Tags manually & auto-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 an Image Upload Button

With JavaScript — Try on CodePen:

uploader
  .open({
    multi: false,
    mimeTypes: ["image/jpeg", "image/png", "image/webp"],
    editor: {
      images: {
        cropShape: "circ", // "rect" also supported.
        cropRatio: 1 / 1   // "1" is enforced for "circ".
      }
    }
  })
  .then(files => alert(JSON.stringify(files)));

Or with HTML — Try on CodePen:

<button data-upload-complete='alert(JSON.stringify(event.files))'
        data-upload-config='{
          "multi": false,
          "mimeTypes": ["image/jpeg", "image/png", "image/webp"],
          "editor": {
            "images": {
              "cropShape": "circ",
              "cropRatio": 1
            }
          }
        }'>
  Upload an Image...
</button>

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 already have a 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.
        cropRatio: 4 / 3,        // width / height. undefined enables freeform (default).
        cropShape: "rect"        // "rect" (default) or "circ".
      }
    },
  })
  .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 = {
  "error!":              "Error!",
  "done":                "Done",
  "addAnotherFile":      "Add another file...",
  "cancel":              "cancel",
  "cancelled!":          "cancelled",
  "continue":            "Continue",
  "crop":                "Crop",
  "finish":              "Finished",
  "finishIcon":          true,
  "maxSize":             "File size limit:",
  "next":                "Next",
  "orDragDropFile":      "...or drag and drop a file.",
  "orDragDropFiles":     "...or drag and drop files.",
  "pleaseWait":          "Please wait...",
  "removed!":            "removed",
  "remove":              "remove",
  "skip":                "Skip",
  "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:

• Beautifully clean UI widget.
• Single & Multi-File Uploads.
• Fluid Layout & Mobile-Friendly.
• Image Cropping.
• 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.

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