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 1.0.1 of the widget and may be changed in the future.


Using our widget is easy. Check out the configuration page to set up a widget of your liking and add it to your form. After that you will get uploaded file UUID or CDN link in associated field instead of file content.

Advanced Configuration

If the wizard we provide is not enough, the details of configuration are discussed in this section.

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.


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

    UPLOADCARE_PUBLIC_KEY = 'demopublickey';


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


Here is a summary of all available options:


Local: data-public-key
Type: string

Your public key.


Local: data-multiple
Global: N/A
Type: boolean

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


Local: data-multiple-max
Global: N/A
Type: integer

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


Local: data-multiple-min
Global: N/A
Type: integer

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.


Local: data-images-only
Global: N/A
Type: boolean

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


Local: data-preview-step
Type: boolean

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


Local: data-crop
Global: N/A
Type: string

Manual crop options (see below).


Local: data-clearable
Type: boolean

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


Local: data-tabs
Type: string

Space-separated ordered list of ways to upload files (e.g. from computer, URL, or Facebook; see below). Every supported upload source is turned on by default.


Local: N/A
Type: string

Locale, of course. English is used by default.


Local: N/A
Type: object

Custom localization options (see below).


Local: N/A
Type: object

Custom localization options (see below).


Local: data-autostore
Type: boolean

If true, files are stored automatically (see below). Turned off by default.


Local: N/A
Type: boolean

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


Local: N/A
Type: boolean

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


Local: data-path-value
Type: boolean

If true, input value is always a CDN link (more about input values below). Turned off by default.

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 (1.0.1) is provided below.

Code File Source Default
url Any URL On
file Local disk On
facebook Facebook On
dropbox Dropbox Off
gdrive Google Drive On
box Box On
skydrive SkyDrive On
instagram Instagram On
evernote Evernote On
vk VK Off

Note that in order to use Dropbox with your account, you need to configure it in account settings.

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 holds the file UUID. When crop has been applied, the value is a CDN link.

There is a global option to always set the value in a unified format. If it's turned on, UUID values will be full CDN links.


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. The one of the things you can do is change upload button color:

.uploader-demo-green .uploadcare-widget-button-open {
    background-color: #16d061; }
.uploader-demo-green .uploadcare-widget-button-open:hover {
    background-color: #15c25a; }

.uploader-demo-yellow .uploadcare-widget-button-open {
    background-color: #fbc701; }
.uploader-demo-yellow .uploadcare-widget-button-open:hover {
    background-color: #edc218; }

Or something more crazy:

.uploader-demo-crazy .uploadcare-widget-button-open {
    cursor: pointer;
    font-family: Arial, Helvetica, sans-serif;
    font-size: 24px;
    font-weight: bold;
    text-shadow: 0 -1px 1px rgba(0,0,0,0.25);
    padding: 9px 14px;
    background-color: #e22092;
    background: linear-gradient(#e85eac, #e02a91);
    border-bottom: 1px solid rgba(0,0,0,0.25);
    box-shadow: 0 1px 3px rgba(0,0,0,0.6);
    transition: transform .25s;
.uploader-demo-crazy .uploadcare-widget-button-open:hover {
    background: linear-gradient(#e14296, #d71876);
    transform: scale(1.05);
.uploader-demo-crazy .uploadcare-widget-dragndrop-area {
    line-height: 3.4;
    margin-top: -1.8em;

You can also customize the upload dialog appearance: most of it has corresponding uploadcare-dialog-* classes. You can find more examples in 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.

  ready: 'Select file',
  buttons: {
    remove: 'Delete'

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 and comes with built-in jQuery. We currently do not supply version without jQuery or version divided into modules. But you can use our jQuery 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 features depends on functionality that lacks in these browsers.

Automatic File Storing

When the “autostore” feature is enabled both in project settings and in the widget, uploaded files are stored to our storage automatically. You don't need to store it manualy. 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 one day. If autostore is turned off, you need to do a separate server-side API call after a form with uploaded files is submitted.

To enable automatic storing in the widget:



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 he will be able to crop it, according to your preferences.

There is a single option to manage crop behavior: data-crop (or UPLOADCARE_CROP globally).

It's can be set to one of the following values:

  • "disabled" — crop disabled (default)
  • "" — 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
  • "200x300" — same as previous, but if the selected area is bigger than 200x300, it will be scaled down to these dimensions
  • "200x300 upscale" — same as previous, but the selected area will be scaled even if it is smaller than the specified size
  • "200x300 minimum" — user will not be able to select an area smaller then 200x300. If uploaded image is smaller then 200x300 itself, it will be upscaled.
  • Crop with no restrictions.


  • Crop with fixed aspect ratio.


  • Fixed-size crop with upscaling.

        data-crop="300x400 upscale"

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.