File Uploader options

Here is a list of all available options for the File Uploader configuration.

pubkey

Your project's Public Key.

Attribute: pubkey

DOM property: pubkey

Type: string

multiple

Allow multiple files to be uploaded.

Attribute: multiple

DOM property: multiple

Type: boolean

Default: true

multipleMin

Minimum number of files that can be selected.

Attribute: multiple-min

DOM property: multipleMin

Type: number

Default: 0

multipleMax

Maximum number of files that can be selected.

Attribute: multiple-max

DOM property: multipleMax

Type: number

Default: 0 - means no limit

confirmUpload

Enables user confirmation for starting uploads.

Attribute: confirm-upload

DOM property: confirmUpload

Type: boolean

Default: false

Available in: regular and inline modes

imageShrink

Saves traffic and storage space by resizing images on a client before uploading. See shrink docs for details.

Attribute: image-shrink

DOM property: imageShrink

Type: string

Default: ''

imgOnly

Accept images only.

Attribute: img-only

DOM property: imgOnly

Type: boolean

Default: false

accept

Native file input accept attribute value. Also affects client validation settings.

Attribute: accept

DOM property: accept

Type: string

Default: ''

externalSourcesPreferredTypes

An ordered, comma-separated list of MIME types.

This setting affects the behavior of the Google Drive source only. Defines a set of preferred MIME types in which Google Workspace documents will be exported upon uploading to Uploadcare. If not set, all types of documents will be exported as PDFs. If a set MIME type is not supported, it will be ignored.

Complete list of supported export MIME types

The asterisk * wildcard can be used for subtypes.

For example, if you want all documents exported in Open XML format, set externalSourcesPreferredTypes as application/vnd.openxmlformats-officedocument.*.

Attribute: external-sources-preferred-types

DOM property: externalSourcesPreferredTypes

Type: comma separated string

Default: ''

store

Store uploaded files. See File storing behavior for details.

Attribute: store

DOM property: store

Type: boolean | 'auto'

Default: 'auto'

cameraMirror

Type: boolean

Attribute: camera-mirror

DOM property: cameraMirror

Default: false

Available in: regular and inline modes

cameraCapture

Type: "user" | "environment" | ""

Attribute: camera-capture

Default: ""

Indicate the value for the capture attribute of the input tag to trigger the native camera dialog.

"user": Indicates that the media should be captured using the device's user-facing camera.
"environment": Suggests using the device's outward-facing camera, which is helpful for capturing images of the environment around the user.
"": Indicates that the user agent should determine the most suitable camera to use.

See W3C HTML Media Capture for details.

sourceList

Comma-separated list of file sources.

Attribute: source-list

DOM property: sourceList

Type: comma separated string

Default: 'local, url, camera, dropbox, gdrive'

Available in: regular and inline modes

Full source list:

local
url
camera
dropbox
gdrive
facebook
gphotos
instagram
flickr
vk
evernote
box
onedrive
huddle

maxLocalFileSizeBytes

Maximum size in bytes for local files.

Attribute: max-local-file-size-bytes

DOM property: maxLocalFileSizeBytes

Type: number

Default: 0 - means no limit

thumbSize

Thumbnail size for images.

Attribute: thumb-size

DOM property: thumbSize

Type: number

Default: 76

showEmptyList

Show the upload list even if it is empty.

Attribute: show-empty-list

DOM property: showEmptyList

Type: boolean

Default: false

Available in: regular and inline modes

useCloudImageEditor

Enable cloud image editing.

Attribute: use-cloud-image-editor

DOM property: useCloudImageEditor

Type: boolean

Default: true

Available in: regular and inline modes

cloudImageEditorTabs

Defines the list of tabs in the cloud image editor. Order matters.

Attribute: cloud-image-editor-tabs

DOM property: cloudImageEditorTabs

Available in: regular and inline modes

Available values:

crop - image cropping, rotating, mirroring, and flipping
tuning - color adjustment
filters - photo filters

Type: comma separated string

Default: 'crop,tuning,filters'

cropPreset

Defines the crop behavior. When uploading images, your users can select a crop area with a defined aspect ratio.

Attribute: crop-preset

DOM property: cropPreset

When useCloudImageEditor is enabled and there is a single file selected, the image editor will be opened automatically. In the other case, images will be cropped automatically with centred alignment without opening the image editor.

Expected format: 'width:height'. For example, '1:1' stands for the square crop. Empty string '' means free crop.

Type: string

Default: ''

Available in: regular and inline modes

remoteTabSessionKey

Key to revoke Custom OAuth access. See OAuth docs for details.

Attribute: remote-tab-session-key

DOM property: remoteTabSessionKey

Type: string

Default: ''

cdnCname

Set Custom CNAME. See Custom CNAME docs for details.

Attribute: cdn-cname

DOM property: cdnCname

Type: string

Default: 'https://ucarecdn.com'

baseUrl

Set a custom upload URL.

Attribute: base-url

DOM property: baseUrl

Type: string

Default: 'https://upload.uploadcare.com'

Set a custom social sources URL.

Attribute: social-base-url

DOM property: socialBaseUrl

Type: string

Default: 'https://social.uploadcare.com'

secureSignature

Set signature for Secure Uploads. See signed uploads docs for details.

Attribute: secure-signature

DOM property: secureSignature

Type: string

Default: ''

secureExpire

Set expire for Secure Uploads. See signed uploads docs for details.

Attribute: secure-expire

DOM property: secureExpire

Type: string

Default: ''

secureUploadsSignatureResolver

Works as DOM property only.

Set a function that resolves Secure Uploads signature and expire asynchronously.

This function will be called before each upload request in case when previous signature and expire are not set or expired.

There are a 10 minutes threshold for the expire value. If the expire value will be expired in 10 minutes, it will be considered as expired and a new value will be requested.

See security and signed uploads docs for details.

Attribute: -

DOM property: secureUploadsSignatureResolver

Type: () => Promise<{ secureSignature: string; secureExpire: string } | null>

Default: null

secureUploadsExpireThreshold

Works together with the secureUploadsSignatureResolver option. Sets the auto-refreshing threshold for Secure Uploads expire value in milliseconds.

The expire value will be considered expired if the difference between the current time and the expire value is less than the threshold. In this case, a new signature and expire will be requested using the secureUploadsSignatureResolver function.

This is needed to prevent the expire value from expiring during the direct uploading method. Files less than 25 MB are uploaded directly to the Uploadcare servers, and the expire value will be checked after the file is uploaded, so it should be valid during the whole upload process.

Files larger than 25 MB are uploaded using the multipart upload method, and the expire value will be checked before the upload starts.

See security and signed uploads docs for details.

Attribute: secure-uploads-expire-threshold

DOM property: secureUploadsExpireThreshold

Type: number

Default: 10 * 60 * 1000 (10 minutes)

secureDeliveryProxy

Set a proxy URL template. See secure delivery docs for details.

Attribute: secure-delivery-proxy

DOM property: secureDeliveryProxy

Type: string

Default: ''

secureDeliveryProxyUrlResolver

Works as DOM property only.

Set a function that resolves the secure delivery proxy URL. It accepts the previewUrl and urlParts arguments and should return the resolved URL itself or a promise that resolves that URL.

Argument urlParts is an object with the deserialized URL parts:

uuid - file UUID.
cdnUrlModifiers - CDN URL modifiers (-/resize/100x/ or '' for example).
fileName - file name ('example.jpg' or '' for example).

See secure delivery docs for details.

Attribute: -

DOM property: secureDeliveryProxyUrlResolver

Type: (previewUrl: string, urlParts: { uuid: string; cdnUrlModifiers: string; fileName: string }) => Promise<string> | string

Default: null

groupOutput

Enables files group creation.

Attribute: group-output

DOM property: groupOutput

Type: boolean

Default: false

metadata

Works as DOM property only. Defines the metadata to be added to uploaded files.

Attribute: -

DOM property: ``

Type:Record<string, string> | (fileEntry: OutputFileEntry) => Promise<Record<string, string>> | Record<string, string>

Default:undefined

removeCopyright

Whitelabeling. Removes copyright.

Attribute: remove-copyright

DOM property: removeCopyright

This feature is available on some paid plans.

Type: boolean

Default: false

debug

Enable debug mode. In debug mode, the debug messages will be logged to the console. The debug messages include the following:

All dispatched events.
Upload Client options.
Other useful information.

Please do not enable debug mode in production because it could lead to a performance issue due to disabled events lazy evaluation.

Attribute: debug

DOM property: debug

Type: boolean

Default: false

localeName

Specifies the locale to use for localization.

See Localization for details.

Attribute: locale-name

DOM property: localeName

Type: string

Default: "en"

localeDefinitionOverride

Works as DOM property only.

Defines overrides to the specified locale definition. It allows easy tweaking of the localization without defining a new locale from scratch.

See Localization for details.

Attribute: -

DOM property: localeDefinitionOverride

Type: Record<string, Record<string, string>>

Default: {}

iconHrefResolver

Works as DOM property only.

Defines a function that resolves the icon sprite URL by its name. The result will be used as the href attribute of the <use> tag. If nothing is returned, the default icon sprite will be used.

See Icons article for details.

Attribute: -

DOM property: iconHrefResolver

Type: (iconName: string) => (string | undefined)

Default: null

fileValidators

Works as DOM property only.

Specify a file validators list. See Validators article for details.

Attribute: -

DOM property: fileValidators

Type: Array<(outputFile: OutputFileEntry, ctx: UploadCtxProvider) => CustomValidatorError>

Default: []

collectionValidators

Works as DOM property only.

Specify a collection validators list. See Validators article for details.

Attribute: -

DOM property: collectionValidators

Type: Array<(outputFile: OutputCollectionState, ctx: UploadCtxProvider) => CustomValidatorError>

Default: []