jQuery uploading widget v3 options

Public key

Type: string
Local: data-public-key
Object key: publicKey

Sets your Uploadcare public key.


Type: boolean
Local: data-multiple
Object key: multiple

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

Multiple max

Type: integer
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

Type: integer
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

Type: boolean
Local: data-images-only
Object key: imagesOnly

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

Preview step

Type: boolean
Local: data-preview-step
Object key: previewStep

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


Type: string
Local: data-crop
Object key: crop

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

Image shrink

Type: 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.


Type: boolean
Local: data-clearable
Object key: clearable

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


Type: string
Local: data-tabs
Object key: tabs

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

Input accept types

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

Sets the accept attribute for the file uploader 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

Type: string
Local: data-preferred-types
Object key: preferredTypes

Some cloud services, such as Google Drive, export document files as PDFs by default, but they can be exported as Word documents, PDFs or plain text.

You can define the behavior by setting a 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

Type: boolean
Local: data-system-dialog
Object key: systemDialog

Forces a system-native file picking dialog to show up instead of our file uploader. That makes the file uploader 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 file uploader.

Multipart minimum size

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

This option sets the file size threshold for multipart uploading. The value ranges from 10485760 (10 MB), which is default, up to 104857600 (100 MB).

If a file size hits the threshold, it gets uploaded in four parallel chunks by 5 MB. Multipart upload makes large file uploading faster. Files go directly to a storage, bypassing our upload servers, and they're quickly available for further use. All files below the threshold get uploaded in one piece.

Note that multipart upload works with local sources only (files and camera).


Type: string
Local: N/A
Object key: N/A

Uploading Widget supports 31 locales.

There currently are: ar az ca cs da de el en es et fr he is it ja ko lv nb nl pl pt ro ru sk sr sv tr uk vi zhTW zh

English locale is used by default.

Locale translations

Type: object
Local: N/A
Object key: N/A

Sets custom localization options.

Locale pluralize

Type: object
Local: N/A
Object key: N/A

Defines pluralization options.

Secure signature

Type: string
Local: data-secure-signature
Object key: secureSignature

The signature is an HMAC/SHA256 hex-encoded hash that includes YOUR_SECRET_KEY and expire strings.

To use signed uploads for your project, you need to make a signature on your back end using your project's Secret Key and provide it to File Uploader. Learn how to make your signature in Signed uploads docs.

Secure expire

Type: 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 signature option that defines a period of your signature validity.

Preview proxy

Type: string
Local: data-preview-proxy
Object key: previewProxy

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

See the article on file uploader signed URLs for details.

Preview URL callback

Type: function
Local: N/A
Object key: previewUrlCallback

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

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

See the article on file uploader signed URLs for details.


Type: object
Local: N/A
Object key: metadata

The option can be used to set metadata object associated with the uploaded file.

Note that metadata supports string values only, any non-string value will be converted to string, including boolean, number, null and undefined.

See Metadata docs for details.

Metadata callback

Type: function
Local: N/A
Object key: metadataCallback

Defines the function that specifies the actual metadata object a file uploader should use to associate with the uploaded file. It's helpful in the case of dynamic metadata object.

Function signature is () => {[key: string]: string}.

If this option is specified, option metadata will be overridden (without merging).

Note that metadata supports string values only, any non-string value will be converted to string, including boolean, number, null and undefined.

See the REST API docs on metadata for details.


Type: 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

Type: boolean
Local: N/A
Object key: N/A

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

CDN base

Type: 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

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

Forces files uploaded with a file uploader 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 file uploader.


Type: 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

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

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

Video preferred MIME types

Type: array
Local: data-video-preferred-mime-types
Object key: videoPreferredMimeTypes

Allows you to specify the MIME types. The first supported by the browser will be used as an option of video stream captured via the file uploader Camera Tab. Refer here to learn more.

Video bits per second

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

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

Camera mirror default

Type: boolean
Local: data-camera-mirror-default
Object key: cameraMirrorDefault

Allows you to set the default state of image/video mirorring in the camera tab. true by default.

Enable video recording

Type: boolean
Local: data-enable-video-recording
Object key: enableVideoRecording

Allows you to enable video recording. true by default. To use the camera with photo only, set to false.

Enable audio recording

Type: boolean
Local: data-enable-audio-recording
Object key: enableAudioRecording

Allows to record audio while using the camera in video mode. true by default. To film video without audio, set it to false.


Type: boolean
Local: data-debug-uploads
Object key: debugUploads

Allows you to enable the output to the console of error descriptions from the server when the upload goes wrong. false by default.

List of the most common server errors:

Server errorsDescription
AccountBlockedErrorAdministrator's account has been blocked. Please, contact support.
AccountUnpaidErrorAdministrator's account has been blocked. Please, contact support.
AccountLimitsExceededErrorAdministrator's account has reached its limits. Please, contact support.
FileSizeLimitExceededErrorFile is too large.
MultipartFileSizeLimitExceededErrorFile is too large.
FileTypeForbiddenOnCurrentPlanErrorUploading of these files types is not allowed.
DownloadFileSizeLimitExceededErrorDownloaded file is too big.

View a complete list of descriptions of system errors in the Upload API Errors tab.

Session key for widget remote tab

Type: string
Local: data-remote-tab-session-key
Object key: remoteTabSessionKey

Generates the end-user part of the two-part key used to encrypt the OAuth token; see more about here. It allows the custom OAuth application to revoke the widget's access to content from connected download sources (Dropbox, Facebook, etc.).