The Widget

Uploadcare comes with a custom widget that is meant to replace your usual <input type="file"> controls. Here is the latest version in action:

  • This documentation is for version 2.5.5 of the widget and may be changed in the future.


There are three easy steps you need to perform to use widget on your page:

  1. Embed our client library via <script> tag in <head> section of each page where Uploadcare widget should be shown. It’s available on our CDN, but feel free to compile it with all your website static files.

    <script src="" charset="utf-8"></script>

    or version without builtin jQuery:

    <script src="" charset="utf-8"></script>
    <script src="" charset="utf-8"></script>
  2. Set your public key. This can go to the <head> of your page:

        UPLOADCARE_PUBLIC_KEY = 'demopublickey';

    The private key is not needed for widget (it wouldn’t be so private if you include it in your page anyway).

  3. Insert widget element to your form.

    <input type="hidden" name="picture" role="uploadcare-uploader" />

    The library looks for inputs with special role attribute, and places widgets there. As soon as the file is uploaded, this input will receive CDN link with file UUID. Your server will receive this value instead of file content.

We recommend to set field with Uploadcare widget as high as possible in your form. Unlike regular input, widget starts uploading immediately after user selects a file, not when the form is submitted. That way users can fill out the rest of the form while upload is in progress. This can be a real time saver.


Widget is highly customizable through widget options. You can check out the configuration page to see some of them in action.

There are two ways to set widget options. Global options are set when page loads, local every time when new widget is created. Changing any options during widget operation won't affect the widget.

Global variables

Specified as global JavaScript variables in a <script> tag, for example:

    UPLOADCARE_PUBLIC_KEY = 'demopublickey';

Local attributes

Specified in the target <input> tag as data-* attributes, for example:


Settings object

Most of widget options can be used within settings object in javascript API.

uploadcare.openDialog(null, {
    publicKey: "demopublickey",
    imagesOnly: true,
    crop: "300x200"

Here is a summary of all available options:

Public key string

Local: data-public-key
Object key: publicKey

Your public key.

Multiple boolean

Global: N/A
Local: data-multiple
Object key: multiple

If true, widget allows selecting and uploading multiple files. Turned off by default.

Multiple max integer

Global: N/A
Local: data-multiple-max
Object key: multipleMax

Maximum number of files allowed in widget. Default value is 0 which means there is no limit.

Multiple min integer

Global: N/A
Local: data-multiple-min
Object key: multipleMin

Minimum number of files allowed in widget. Default value is 1. Note that setting 0 bears no meaning as file group should have at least one file.

Images only boolean

Local: data-images-only
Object key: imagesOnly

If true, only image files are allowed to be uploaded. Turned off by default.

Preview step boolean

Local: data-preview-step
Object key: previewStep

If true, dialog won't be closed after file selection. Instead preview of selected file will be shown to user. Turned off by default.

Crop string

Local: data-crop
Object key: crop

Manual crop options (see below). If the uploaded file is an image, user will be able to select an area. This option does not force images only, though.

Works together with multiple option starting from version 2.3.0.

Image shrink string

Local: data-image-shrink
Object key: imageShrink

Reduce image size before uploading to save traffic and storage space. See detailed syntax below. This option does not force images only.

Clearable boolean

Local: data-clearable
Object key: N/A

Allows user to remove uploaded file from widget. Please note that files are not deleted from your account.

Tabs string

Local: data-tabs
Object key: tabs

Space-separated ordered list of ways to upload files (e.g. from computer, URL, or Facebook; see below).

Input accept types string

Local: data-input-accept-types
Object key: inputAcceptTypes

Set accept attribute for file choosing dialog. By default accept will be image/* if images only is set or empty if not. null value means accept always should be empty regeardless of images only. You can find other values in specification. Please note that this is not replacement of validation because user can still choose any file by drag & drop or from URL.

Preferred types string

Local: data-preferred-types
Object key: preferredTypes

Space-separated ordered list of preferred MIME types. Common parts can be matched by asterisk: image/* application/vnd.openxmlformats-officedocument.*. If none of MIME types is matched or preferred types are not set, default formats are used.

Some of cloud services offer several file formats for export. For example Google document can be exported as Word document, PDF or plain text.

System dialog boolean

Local: data-system-dialog
Object key: N/A

Open native file choosing dialog instead of Uploadcare dialog. Thus, widget behavior gets as close as possible to usual <input type="file">. This option disables social networks and cloud services, crop and preview. Multiple file selection works though. In old browsers versions this option does not work and widget falls back to Uploadcare dialog.

Locale string

Local: N/A
Object key: N/A

Locale, of course. English is used by default.

Locale translations object

Local: N/A
Object key: N/A

Custom localization options (see below).

Locale pluralize object

Local: N/A
Object key: N/A

Custom localization options (see below).

Live boolean

Local: N/A
Object key: N/A

If true, inputs are initialized automatically (see below). Turned on by default.

Manual start boolean

Local: N/A
Object key: N/A

If true, input initialization is invoked manually (see below). Turned off by default.

CDN base url

Local: data-cdn-base
Object key: cdnBase

Schema and CDN domain. Can be changed to one of predefined values or your custom CNAME. Default value is

Do not store boolean

Local: data-do-not-store
Object key: doNotStore

Set it to true when autostore is enabled in the project, but you don't want to store files uploaded with particular widget.

Validators array

Global: N/A
Local: N/A
Object key: validators

Javascript-only option. It is an array of validation functions. See validators documentation.

Boolean options

All boolean options are set globally with normal JavaScript boolean values.


For local settings in HTML tag attributes you can use any value as true, even an empty one. To set a local option to false explicitly, the attribute value should either be "false" or "disabled", literally.

Setting a local option to true:

<input data-option="data-option" />
<input data-option="true" />
<input data-option="" />
<input data-option>

Setting a local option to false:

<input data-option="false" />
<input data-option="disabled" />

Tabs (Upload Sources)

The widget can upload files from disk, URLs, and many social sites. Each upload source has its own tab in the widget dialog.

A full list of tabs supported in the latest widget version (2.5.5) is provided below.

Code File Source Default
file Local disk On
camera Local webcam On
url Any URL On
facebook Facebook On
gdrive Google Drive On
dropbox Dropbox On
instagram Instagram On
evernote Evernote On
flickr Flickr On
skydrive OneDrive On
box Box Off
vk VK Off
huddle Huddle Off

The set can be reconfigured by specifying the ones you need in a space-separated value.


<script>UPLOADCARE_TABS = 'url file facebook';</script>

or locally:

<input type="hidden" role="uploadcare-uploader" data-tabs="url file facebook" />

Input Value

The value of [role=uploadcare-uploader] input is either empty or CDN link with file UUID.

If you externally set the value of the input and trigger the DOM change event, it will be reflected in the widget. For example, setting it to a file UUID or a CDN link will show that file as uploaded in the widget. You can do this on a live widget or even before it's actually loaded.

Example of a predefined value:


    Also valid:


The widget is designed to inherit styles from your page as much as possible and to be highly customizable at the same time. All elements scale with font size.

Times New Roman, 12px:

Courier New, 18px:

Widget is thoroughly annotated with CSS classes, which can all be styled on top of defaults. You can find the class for the part you want by inspecting the widget element, or sifting through the original source.

You can also customize the upload dialog appearance: most of it has corresponding uploadcare-dialog-* classes.

You can find more examples in cookbook and customization tutorial.

Custom Localization

It's possible that your locale is not yet available in the widget. When this is the case, a good idea is to contribute it by forking the main repository and adding a localization file here.

However, when you need to override text in specific parts of the widget, this can be configured globally.

  buttons: {
    cancel: 'Cancel',
    remove: 'Remove',
    choose: {
      files: {
        one: 'Choose a file',
        other: 'Choose files'
      images: {
        one: 'Choose an image',
        other: 'Choose images'

Compare the structure above with default English localization. This overrides two strings in the original localization.

If a string is both missing in the selected localization and is not overriden, English is used as a fallback. English is always the most complete localization for the lastest version of the widget.

You might also need to override strings that describe an amount of things. For example, “1 file” and “3 files”. These expect a special structure, as seen under the file: key in the English localization.

Such strings are selected based on the output of a pluralization function, which, given a number, returns the name of a subkey that needs to be accessed.

function pluralize(number) {
  // do something
  return 'some_subkey';

In the case of English there are only two such subkeys: one and other. However, languages with more complex pluralization rules have it harder. For example, take a look at file: subkeys in Russian.

As you may have already noticed, to format a number into pluralized strings, a %1 sequence is used.

Each locale provided by the widget comes with its own pluralization rules, but if you need to override them, you can write your custom function and assign in to the UPLOADCARE_LOCALE_PLURALIZE variable.

For example, a configuration below would make the widget use the message under the some subkey for 2 up to 10 files.

  file: {
    one: 'Only one file! :(',
    some: 'Only %1 files. Upload more.',
    many: '%1 files!! That\'s a lot.'
  if (n === 1) return 'one';
  if (n > 1 && n <= 10) return 'some';
  return 'many';


Widget does not depend on any external libraries except jQuery. We supply two versions of widget: with built-in jQuery and without (see usage). If you are using version with built-in jQuery, you can use it on your page:

var $ = uploadcare.jQuery;
$('body').append('It works!');

Widget should work perfectly on last two versions of major desktop browsers: Internet Explorer, Firefox, Google Chrome, Safari and Opera. Most likely everything is working properly in older versions of Firefox, Google Chrome, Safari and Opera.

We support Internet Explorer 8 and 9 partially: some of widget's features depend on functionality that lacks in these browsers. Additionally, we are using built-in jQuery 2.1.x which does not support IE 8. If you need to support IE 8 you must use version without built-in jQuery and use your jQuery 1.11.x.

Automatic File Storing

When the “autostore” feature is enabled in project settings, uploaded files are stored to our storage automatically. You don't need to store them explicitly. This may be convenient when your application retains most (or all) of the uploaded files.

Files that are not stored after upload are deleted after 24 hours. If autostore is turned off, you need to do a separate server-side API call after a form with uploaded files is submitted.

If you enabled autostore in project settings, but don't want to store files uploaded with particular widget, set appropriate option:



By default, every new [role=uploadcare-uploader] element that appears on the page (at any time) is initialized as a widget, after about ~100 ms. A single JavaScript timer is used to provide this behavior. It shouldn't impact perfomance in typical applications. However, if every cycle counts and you feel this is taxing, there's an option to turn it off.


In this case you would have to deal with widget inputs added after page load manually.

However all widgets served with the page would still be initialized on its load. Sometimes, this is not ideal, if you require some preparations before instantiating our widgets. In such a case you can use the UPLOADCARE_MANUAL_START flag in conjunction with the uploadcare.start() function, which is passed a settings object that will override global settings. Any global setting can be passed, but note that keys are camel-cased, not capitalized with underscores.


jQuery(function($) {
  var $.getJSON('/uploadcare.json', function(data) {
      publicKey: data.publicKey, // overrides UPLOADCARE_PUBLIC_KEY
      crop: data.crop // overrides UPLOADCARE_CROP

Manual Crop

You can enable custom crop in the widget. After a user selects a file she will be able to crop it, according to your settings. Original file will be uploaded to your project, but additional crop operations will be included in resulting CDN link.

Crop options is a string with one or more crop presets. Presets are divided by commas. When more than one preset is defined, user can pick any of them on crop step.

Each preset consists of a size definition and optional keyword.

  • "disabled" — crop is disabled. Can't be combined with other presets;
  • "" or "free" — crop enabled and the user will be able to select any area on an image;
  • "2:3" — user will be able to select an area with aspect ratio 2:3;
  • "300x200" — same as previous, but if the selected area is bigger than 300x200, it will be scaled down to these dimensions;
  • "300x200 upscale" — same as previous, but the selected area will be scaled even if it is smaller than the specified size;
  • "300x200 minimum" — user will not be able to select an area smaller than 300x200. If uploaded image is smaller than 300x200 itself, it will be upscaled.
  • Crop with no restrictions.

    <input type="hidden" role="uploadcare-uploader" data-images-only
           data-crop="" />

  • Five presets with differnt aspect ratio, first of them is free crop.

    <input type="hidden" role="uploadcare-uploader" data-images-only
           data-crop="free, 16:9, 4:3, 5:4, 1:1" />

  • Crop with fixed aspect ratio.

    <input type="hidden" role="uploadcare-uploader" data-images-only
           data-crop="4:3" />

  • Fixed-size crop with upscaling.

    <input type="hidden" role="uploadcare-uploader" data-images-only
           data-crop="400x300 upscale" />

Shrink Images Before Uploading

Sometimes you don't need high resolution original image to be uploaded. At the same time sending large image can be expensive and too long for user. Most obvious case is sending 10+ megapixel images from mobile phone camera over cellular network.

Image shrink options is a string with desired resolution and optional result JPEG quality.

  • 800x600 — shrink image to 0.48 megapixels with default JPEG quality (80%).
  • 1600x1600 95% — shrink image to 2.5 megapixels with 95% JPEG quality.

Desired resolution can not exceed 5 MP. All EXIF info from the original image (including orientation, camera model and settings, geolocation) will be copied to resized image.

Image will not be shrinked in the following cases:

  • if browser does not support all required APIs;
  • if image is uploaded from social sources or URL;
  • if image is less than two times bigger than desired. For example image with resolution 2560x1560 (4 MP) will not be shrinked to 1600x1600 (2.5 MP), but 2448x3264 (8 MP) will. The reason is that in the first case quality drop will be significant with relatively small filesize drop.
  • Shrink to 1024x1024 pixels.

    <input type="hidden" role="uploadcare-uploader"
           data-image-shrink="1024x1024" data-preview-step="">

  • Multiple widget shrinks to 640x480 pixels (0.3 MP).

    <input type="hidden" role="uploadcare-uploader"
           data-multiple="" data-image-shrink="640x480">

Mobile Layout

Starting from version 1.0.0 web widget can be properly used on mobile devices. On small screens the dialog is opened on full screen and layout is changed for better user experience. This feature is turned on automatically on pages with proper <meta name="viewport"> tag. Viewport tag allows to tell what screen size is expected when you created the page. It is required for all responsive web sites. If your site does not have responsive design but you want to have mobile Uploadcare widget on mobile devices you can include relatively safe viewport tag to your page:

<meta name="viewport" content="width=device-width, initial-scale=1">

This tag will trigger mobile browser to show your page with 1:1 initial zoom, but will still allow users to change zoom manually.