jQuery File Uploader options

Public key

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

Sets your Uploadcare public key.

Multiple

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

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

Multiple max

Type: integer
Global: UPLOADCARE_MULTIPLE_MAX
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
Global: UPLOADCARE_MULTIPLE_MIN
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
Global: UPLOADCARE_IMAGES_ONLY
Local: data-images-only
Object key: imagesOnly

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

Preview step

Type: boolean
Global: UPLOADCARE_PREVIEW_STEP
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.

Crop

Type: string
Global: UPLOADCARE_CROP
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
Global: UPLOADCARE_IMAGE_SHRINK
Local: data-image-shrink
Object key: imageShrink

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

Clearable

Type: boolean
Global: UPLOADCARE_CLEARABLE
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.

Tabs

Type: string
Global: UPLOADCARE_TABS
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
Global: UPLOADCARE_INPUT_ACCEPT_TYPES
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
Global: UPLOADCARE_PREFERRED_TYPES
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
Global: UPLOADCARE_SYSTEM_DIALOG
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
Global: UPLOADCARE_MULTIPART_MIN_SIZE
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).

Locale

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

The uploading widget supports locales.

There currently are:

English locale is used by default.

Locale translations

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

Sets custom localization options.

Locale pluralize

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

Defines pluralization options.

Secure signature

Type: string
Global: UPLOADCARE_SECURE_SIGNATURE
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
Global: UPLOADCARE_SECURE_EXPIRE
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
Global: UPLOADCARE_PREVIEW_PROXY
Local: data-preview-proxy
Object key: previewProxy

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

Preview URL callback

Type: function
Global: UPLOADCARE_PREVIEW_URL_CALLBACK
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.

Metadata

Type: object
Global: UPLOADCARE_METADATA
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
Global: UPLOADCARE_METADATA_CALLBACK
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 File metadata REST API for details.

Live

Type: boolean
Global: UPLOADCARE_LIVE
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
Global: UPLOADCARE_MANUAL_START
Local: N/A
Object key: N/A

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

CDN base

Type: url
Global: UPLOADCARE_CDN_BASE
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
Global: UPLOADCARE_DO_NOT_STORE
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.

Validators

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
Global: UPLOADCARE_AUDIO_BITS_PER_SECOND
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 mediarecorder options to learn more.

Video preferred MIME types

Type: array
Global: UPLOADCARE_VIDEO_PREFERRED_MIME_TYPES
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 mediarecorder options to learn more.

Video bits per second

Type: number
Global: UPLOADCARE_VIDEO_BITS_PER_SECOND
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 mediarecorder options to learn more.

Camera mirror default

Type: boolean
Global: UPLOADCARE_CAMERA_MIRROR_DEFAULT
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
Global: UPLOADCARE_ENABLE_VIDEO_RECORDING
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
Global: UPLOADCARE_ENABLE_AUDIO_RECORDING
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.

Debugging

Type: boolean
Global: UPLOADCARE_DEBUG_UPLOADS
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:

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

Session key for widget remote tab

Type: string
Global: UPLOADCARE_REMOTE_TAB_SESSION_KEY
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 OAuth token. It allows the custom OAuth application to revoke the widgets access to content from connected download sources (Dropbox, Facebook, etc.).