Widget configuration

  • This documentation is for the version 3.6.1 of the widget. If you're looking for the widget v2 docs, check here.

Live config

Uploadcare Widget is highly customizable through widget options. You can test many options interactively using our configuration page. This page also provides you with ready-to-integrate widget snippets.

There are three ways to set widget options:

  • Globally, when your page loads.
  • Locally, when a new widget is created.
  • Via the settings object.

Note, changing any options during widget operation does not affect its behavior.

Global variables

Globals are specified as global JavaScript variables in your <script> tag. For example,

  UPLOADCARE_PUBLIC_KEY = 'demopublickey';

Local attributes

Local options are specified in the target <input> tag as data-* attributes. For example,

<input type="hidden" role="uploadcare-uploader"

Settings object

Most of the widget options can also be set within the settings object. See our JavaScript API reference for details. For example,

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

Widget options summary:

Public key string

Local: data-public-key
Object key: publicKey

Sets your Uploadcare public key.

Multiple boolean

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

If true, the widget allows selecting and uploading multiple files. false by default.

Multiple max integer

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

Sets the maximum number of files that can be selected for a single upload. Defaults to 0 which stands for no limit.

Multiple min integer

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

Sets the minimal number of files that can be selected for a single upload. The default value is 1. Note, there is no point in setting this option to 0 since there should be at least one file in a file group.

Images only boolean

Local: data-images-only
Object key: imagesOnly

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

Preview step boolean

Local: data-preview-step
Object key: previewStep

If true, the preview step is present after selecting files. Otherwise, the widget dialog closes when the selection is complete. false by default.

Crop string

Local: data-crop
Object key: crop

Defines the in-widget manual crop behavior. When uploading images, your users can select a crop area. This option does not force your widget to accept images only. The option also works in the multi-file mode since version 2.3.0.

Image shrink string

Local: data-image-shrink
Object key: imageShrink

Saves traffic and storage space by resizing images on a client before uploading. See the detailed option description for details. Using the client-side resize does not force the images only option.

Clearable boolean

Local: data-clearable
Object key: N/A

Allows users to remove uploaded files from the widget. Note, those files are not deleted from your Uploadcare account.

Tabs string

Local: data-tabs
Object key: tabs

Allows you to define which upload sources you want to use with the widget. The value is represented by a space-separated ordered list of upload source names. See this article for details.

Input accept types string

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

Sets the accept attribute for the widget dialog. If the images only option is disabled, the value is empty. Otherwise, the default value is image/*. null means accept should be kept empty regardless of the images only value. You can discover the other possible values in this specification. Note, this is not a replacement for our file validation because your users will still be able to choose any file via drag&drop or from URL.

Preferred types string

Local: data-preferred-types
Object key: preferredTypes

Defines the list of preferred MIME types. The list should be ordered and contain space-separated MIME types. Common parts can be marked with asterisks: image/* application/vnd.openxmlformats-officedocument.*. If no MIME types match the criteria or preferred types aren’t set, default formats are used. Keep in mind that some cloud services can export data in different formats. 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

Forces a system-native file picking dialog to show up instead of our widget. That makes the widget behavior as close as possible to the generic <input type="file">. Native behavior is achieved at the expense of support for uploading content from social media and cloud storage, manual crop, and preview step. Multi-file selection would still work. The option does not work in old browser versions: the dialog falls back to the widget.

Multipart minimum size integer

Local: data-multipart-min-size
Object key: multipartMinSize

This option is only applicable when handling local files. Sets the multipart uploading file size threshold. The value is limited to the range from 10485760 (10 MB) to 104857600 (100 MB) and defaults to 26214400 (25 MB).

  • When your file size is above the threshold, it gets uploaded in a multipart mode: in parallel chunks. Multipart uploads are faster, but files uploaded in chunks are not treated as images and can only be delivered via CDN as is.
  • When your file size is below the threshold, it gets uploaded as a single chunk, which is slower, but allowing to treat that file as an image and apply any CDN API operations.

Locale string

Local: N/A
Object key: N/A

Uploadcare Widget supports a good number of locales.

There currently are:

English locale is used by default.

Locale translations object

Local: N/A
Object key: N/A

Sets custom localization options.

Locale pluralize object

Local: N/A
Object key: N/A

Defines pluralization options.

Secure signature string

Local: data-secure-signature
Object key: secureSignature

In case you enable signed uploads for your project, you’d need to provide the widget with signature and expire. Read more about signed uploads in our docs.

The signature is an MD5 hex-encoded hash from a concatenation of secret_key and expire.

Works together with the secure expire option.

Secure expire integer

Local: data-secure-expire
Object key: secureExpire

Stands for the Unix time to which the signature is valid, e.g., 1454902434.

Works together with the "secure expire" option that defines a period of your signature validity.

Preview proxy string

Local: data-preview-proxy
Object key: previewProxy

The option can be used with Authenticated URLs. Defines your proxy backend URL.

See the article on Widget Secure URLs for details.

Preview URL callback function

Local: N/A
Object key: previewUrlCallback

The option can be used with Authenticated URLs. Defines the function that specifies which URL a widget should use for image previews. Function signature is (originalUrl, fileInfo) => previewUrl.

If this option is specified, option previewBase will be ignored. So you should use one of them, not both.

See the article on Widget Secure URLs for details.

Live boolean

Local: N/A
Object key: N/A

If true, inputs on your page are initialized automatically, see this article for details. true by default.

Manual start boolean

Local: N/A
Object key: N/A

If true, input initialization is invoked manually. false by default.

CDN base url

Local: data-cdn-base
Object key: cdnBase

Defines your schema and CDN domain. Can be changed to one of the predefined values or your custom CNAME. Defaults to https://ucarecdn.com/.

Do not store boolean

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

Forces files uploaded with a widget not to be stored. For instance, you might want to turn this on when automatic file storing is enabled in your project, but you do not want to store files uploaded with a particular widget.

Validators array

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

JavaScript-only option. Defines an array of validation functions. See validators documentation.

Audio bits per second number

Local: data-audio-bits-per-second
Object key: audioBitsPerSecond

Allows you to adjust the quality of an audio recorded via the widget Camera Tab. Refer here to learn more.

Video bits per second number

Local: data-video-bits-per-second
Object key: videoBitsPerSecond

Allows you to adjust the quality of a video stream captured via the widget Camera Tab. Refer here to learn more.

Boolean options

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


When setting boolean options locally in HTML tag attributes, any value is interpreted as true, even an empty one. However, when setting local options to false, the respective value should strictly be either "false" or "disabled".

Setting local options to true,

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

Setting local options to false,

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

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.