Package Exports

uploader
uploader/dist/main.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (uploader) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

File & Image Uploader
(With Integrated Cloud Storage)

Get Started — Try on CodePen

Supported Frameworks:
React • Vue • Angular • jQuery • Plain JS

Supported Features:
Image Cropping • Image Uploads • Multi-file Uploads • Drag-and-Drop • 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"
});

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://upcdn.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://upcdn.io/FW25...",        // The uploaded file URL.
    fileSize: 12345,                            // File size in bytes.
    mime: "image/jpeg",                         // File MIME type.
    suggestedOptimization: {
      transformationUrl: "https://upcdn.io/..", // 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).

🌐 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.
    styles: {
      colors: {
        primary: "#377dff",      // Primary color (e.g. buttons).
        active: "#528fff"        // Active/hover color (inferred from primary by default).
      },
      fontSizes: {
        base: 16                 // Base font size (px).
      }
    },
    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://upcdn.io/W142hJkHhVSQ5ZQ5bfqvanQ

Resize with:

https://upcdn.io/W142hJkHhVSQ5ZQ5bfqvanQ/thumbnail

Auto-crop with:

https://upcdn.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 »

Building From Source

Please read: BUILD.md

Contribute

If you would like to contribute to Uploader:

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

For more examples, see CodePen and CodeSandbox.

License

MIT

uploader

Package Exports

Readme

Get Started — Try on CodePen

Installation

Usage

Initialize

Open the Modal

Get the Result

👀 More Examples

Creating an Image Upload Button

Creating a "Single File" Upload Button

Creating a "Multi File" Upload Button

Creating a Dropzone

🌐 API Support

⚡ Need a Lightweight Client Library?

⚙️ Configuration

🏳️ Localization

📷 Resizing & Cropping Images

🎯 Features

Building From Source

Contribute

License