> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# File Uploader options

> List of all available options for the File Uploader configuration.

Here is a list of all available options for the File Uploader
[basic configuration](/docs/file-uploader/configuration/#basic-configuration).

* [Public key](#pubkey)
* [Multiple files](#multiple)
* [Multiple files min](#multiple-min)
* [Multiple files max](#multiple-max)
* [Confirm upload](#confirm-upload)
* [Image shrink](#image-shrink)
* [Images only](#img-only)
* [Accept](#accept)
* [External sources preferred types](#external-sources-preferred-types)
* [Store](#store)
* [Camera mirror](#camera-mirror)
* [Camera capture](#camera-capture)
* [Source list](#source-list)
* [Top level origin](#top-level-origin)
* [Max local file size bytes](#max-local-file-size-bytes)
* [Thumb size](#thumb-size)
* [Show empty list](#show-empty-list)
* [Use cloud image editor](#use-cloud-image-editor)
* [Cloud image editor tabs](#cloud-image-editor-tabs)
* [Cloud image editor auto open](#cloud-image-editor-auto-open)
* [Cloud image editor mask href](#cloud-image-editor-mask-href)
* [Crop preset](#crop-preset)
* [Remote tab session key](#remote-tab-session-key)
* [CDN CNAME](#cdn-cname)
* [Base URL](#base-url)
* [Social base URL](#social-base-url)
* [Auth token](#auth-token)
* [Secure signature](#secure-signature)
* [Secure expire](#secure-expire)
* [Secure uploads signature resolver](#secure-uploads-signature-resolver)
* [Secure uploads expire threshold](#secure-uploads-expire-threshold)
* [Secure delivery proxy](#secure-delivery-proxy)
* [Secure delivery proxy URL resolver](#secure-delivery-proxy-url-resolver)
* [Group output](#group-output)
* [Retry throttled request max times](#retry-throttled-request-max-times)
* [Retry network error max times](#retry-network-error-max-times)
* [Multipart min file size](#multipart-min-file-size)
* [Multipart chunk size](#multipart-chunk-size)
* [Max concurrent requests](#max-concurrent-requests)
* [Multipart max concurrent requests](#multipart-max-concurrent-requests)
* [Multipart max attempts](#multipart-max-attempts)
* [Check for URL duplicates](#check-for-url-duplicates)
* [Save URL for recurrent uploads](#save-url-for-recurrent-uploads)
* [Metadata](#metadata)
* [Tags](#tags)
* [Copyright removing](#remove-copyright)
* [Debug mode](#debug)
* [Locale name](#locale-name)
* [Locale definition override](#locale-definition-override)
* [Icon href resolver](#icon-href-resolver)
* [File Validators](#file-validators)
* [Validation timeout](#validation-timeout)
* [Validation concurrency](#validation-concurrency)
* [Collection Validators](#collection-validators)
* [Enable video recording (deprecated)](#enable-video-recording)
* [Enable audio recording](#enable-audio-recording)
* [Max video recording duration](#max-video-recording-duration)
* [Camera modes](#camera-modes)
* [Default camera mode](#default-camera-mode)
* [Files view mode](#files-view-mode)
* [Grid show file names](#grid-show-file-names)
* [Quality insights](#quality-insights)
* [Paste scope](#paste-scope)
* [Dynamic button view mode](#dynamic-button-view-mode)
* [Dynamic button show first icon](#dynamic-button-show-first-icon)
* [Plugins](#plugins)

### pubkey \[#pubkey]

Your project's Public Key.

Attribute: `pubkey`

DOM property: `pubkey`

Type: `string`

### multiple \[#multiple]

Allow multiple files to be uploaded.

Attribute: `multiple`

DOM property: `multiple`

Type: `boolean`

Default: `true`

### multipleMin \[#multiple-min]

Minimum number of files that can be selected.

Attribute: `multiple-min`

DOM property: `multipleMin`

Type: `number`

Default: `0`

### multipleMax \[#multiple-max]

Maximum number of files that can be selected.

Attribute: `multiple-max`

DOM property: `multipleMax`

Type: `number`

Default: `0`: means no limit

### confirmUpload \[#confirm-upload]

Enables user confirmation for starting uploads.

Attribute: `confirm-upload`

DOM property: `confirmUpload`

Type: `boolean`

Default: `false`

Available in: regular and inline modes

### imageShrink \[#image-shrink]

Saves traffic and storage space by resizing images on a client before uploading.
See [shrink](/docs/file-uploader/image-shrink/) docs for details.

Attribute: `image-shrink`

DOM property: `imageShrink`

Type: `string`

Default: `''`

### imgOnly \[#img-only]

Accept images only.

Attribute: `img-only`

DOM property: `imgOnly`

Type: `boolean`

Default: `false`

### accept \[#accept]

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

Attribute: `accept`

DOM property: `accept`

Type: `string`

Default: `''`

### externalSourcesPreferredTypes \[#external-sources-preferred-types]

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](https://developers.google.com/drive/api/guides/ref-export-formats)

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]

Store uploaded files. See [File storing behavior](/docs/uploads/storage/#file-storing-behavior) for details.

Attribute: `store`

DOM property: `store`

Type: `boolean | 'auto'`

Default: `'auto'`

### cameraMirror \[#camera-mirror]

Type: `boolean`

Attribute: `camera-mirror`

DOM property: `cameraMirror`

Default: `false`

Available in: regular and inline modes

### cameraCapture \[#camera-capture]

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](https://w3c.github.io/html-media-capture#the-capture-idl-attribute) for details.

### sourceList \[#source-list]

Comma-separated list of file sources.

Attribute: `source-list`

DOM property: `sourceList`

Type: `comma separated string`

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

Full source list:

* `local`
* `url`
* `camera`
* `dropbox`
* `gdrive`
* `facebook`
* `gphotos`
* `box`
* `onedrive`

Custom upload sources can be added via the [Plugin API](/docs/file-uploader/plugins/).

### topLevelOrigin \[#top-level-origin]

Specifies the origin for top-level frame communication. It's needed for Google Drive integration in case when the File Uploader is embedded in a cross-origin iframe.

For example, if your File Uploader is embedded in a cross-origin iframe on `https://example.com`, you should set this option to `https://example.com`.

Attribute: `top-level-origin`

DOM property: `topLevelOrigin`

Type: `string`

Default: `''`

### maxLocalFileSizeBytes \[#max-local-file-size-bytes]

Maximum size in bytes for local files.

Attribute: `max-local-file-size-bytes`

DOM property: `maxLocalFileSizeBytes`

Type: `number`

Default: `0`: means no limit

### thumbSize \[#thumb-size]

Thumbnail size for images.

Attribute: `thumb-size`

DOM property: `thumbSize`

Type: `number`

Default: `76`

### showEmptyList \[#show-empty-list]

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 \[#use-cloud-image-editor]

Enable cloud image editing.

Attribute: `use-cloud-image-editor`

DOM property: `useCloudImageEditor`

Type: `boolean`

Default: `true`

### cloudImageEditorTabs \[#cloud-image-editor-tabs]

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

Attribute: `cloud-image-editor-tabs`

DOM property: `cloudImageEditorTabs`

Available values:

* `crop`: image cropping, rotating, mirroring, and flipping
* `tuning`: [color adjustment](/docs/effects-enhancements/#image-colors-operations)
* `filters`: [photo filters](/docs/effects-enhancements/#image-photo-filters)

Type: `comma separated string`

Default: `'crop,tuning,filters'`

### cropPreset \[#crop-preset]

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'` defines a square crop, and '16:9' sets a widescreen crop.
You can also specify multiple aspect ratios by separating them with commas, e.g.: `'1:1, 16:9'`.
To allow free cropping, include the free option, for example: `'free, 1:1, 16:9'`.

Type: `comma separated string`

Default: `''`

### remoteTabSessionKey \[#remote-tab-session-key]

Key to revoke Custom OAuth access. See [OAuth docs](/docs/upload-sources/#oauth) for details.

Attribute: `remote-tab-session-key`

DOM property: `remoteTabSessionKey`

Type: `string`

Default: `''`

### cdnCname \[#cdn-cname]

Set Custom CNAME. See [Custom CNAME docs](/docs/delivery/cdn/#settings) for details.

If you do not set this option, the CDN CNAME will be determined automatically based on your public key.
You usually don't need to configure it manually unless you have a custom CDN domain.

Attribute: `cdn-cname`

DOM property: `cdnCname`

Type: `string`

Default: `'https://:subdomain.ucarecd.net'`

Actual value depends on your account settings.

New accounts use dedicated subdomains on `*.ucarecd.net`, while older ones may still use `ucarecdn.com`.

### baseUrl \[#base-url]

Set a custom upload URL.

Attribute: `base-url`

DOM property: `baseUrl`

Type: `string`

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

### socialBaseUrl \[#social-base-url]

Set a custom social sources URL.

Attribute: `social-base-url`

DOM property: `socialBaseUrl`

Type: `string`

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

### authToken \[#auth-token]

A token for [signed uploads](/docs/security/secure-uploads/), sent with every
Upload API request. Needs File Uploader 1.35.1 or later. Versions that predate
the option ignore it without a warning and the upload goes out unsigned.

Pass a function and the uploader caches the token and replaces it 30 seconds
before it expires, and retries an upload once with a new token when Uploadcare
refuses the old one as expired or spent. A new function on each render, as in React,
keeps the cached token. A plain token gets neither: it is sent as given, never
refreshed and never retried, so its lifetime must cover the whole upload. Leave
it unset to upload without a token. A function that returns nothing fails the
upload with an `AUTH_TOKEN_ERROR`.

A `{ getToken, invalidate }` object works in place of the function when you
keep your own cache. An [`AuthTokenCache`](https://github.com/uploadcare/uploadcare-js-api-clients/tree/master/packages/signed-uploads#caching-the-token-in-the-browser) instance is already
this shape, so you can pass one straight in. The uploader then adds none of
its own and calls your `invalidate()` when a token is refused.

Takes precedence over `secureSignature`, `secureExpire` and
`secureUploadsSignatureResolver`, which are dropped when it is set.

With [React File Uploader](/docs/integrations/react-file-uploader/) this is an
ordinary prop, function and all. On the web component, a function has to be set
as a [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties)
rather than an attribute. The `auth-token` attribute carries a plain token only,
and writing it after setting a function replaces the function.

[Signed uploads](/docs/security/secure-uploads/) covers issuing the
tokens, and [`invalidateAuthToken()`](/docs/file-uploader/api/#invalidate-auth-token)
drops a cached one.

> **Note**
>
> **Note:** Replacing a token early needs a readable `exp`. A token the
> uploader cannot parse is cached and never refreshed on its own, so invalidate
> it yourself.

Attribute: `auth-token`

DOM property: `authToken`

Type: `string | (() => string | Promise<string>) | { getToken, invalidate } | null`

Default: `null`

### secureSignature \[#secure-signature]

Set `signature` for signed uploads. See the
[signature reference](/docs/api/upload/authentication/#signature) for details,
or [`authToken`](#auth-token) for the token scheme recommended for new
integrations.

Attribute: `secure-signature`

DOM property: `secureSignature`

Type: `string`

Default: `''`

### secureExpire \[#secure-expire]

Set `expire` for signed uploads. See the
[signature reference](/docs/api/upload/authentication/#signature) for details.

Attribute: `secure-expire`

DOM property: `secureExpire`

Type: `string`

Default: `''`

### secureUploadsSignatureResolver \[#secure-uploads-signature-resolver]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Set a function that resolves signed 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](/docs/file-uploader/security/#secure-uploading) and the [signature reference](/docs/api/upload/authentication/#signature) for details.

Attribute: `-`

DOM property: `secureUploadsSignatureResolver`

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

Default: `null`

### secureUploadsExpireThreshold \[#secure-uploads-expire-threshold]

Works together with the `secureUploadsSignatureResolver` option.
Sets the auto-refreshing threshold for signed uploads `expire` value in milliseconds.

> **Note**
>
> **Note:** This applies to signatures only. An [`authToken`](#auth-token) is replaced by the uploader's own cache 30 seconds before the token expires, and this option has no effect on it.

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](/docs/file-uploader/security/#secure-uploading) and the [signature reference](/docs/api/upload/authentication/#signature) for details.

Attribute: `secure-uploads-expire-threshold`

DOM property: `secureUploadsExpireThreshold`

Type: `number`

Default: `10 * 60 * 1000` (10 minutes)

### secureDeliveryProxy \[#secure-delivery-proxy]

Set a proxy URL template. See [secure delivery](/docs/file-uploader/security/#secure-delivery-proxy)
docs for details.

Attribute: `secure-delivery-proxy`

DOM property: `secureDeliveryProxy`

Type: `string`

Default: `''`

### secureDeliveryProxyUrlResolver \[#secure-delivery-proxy-url-resolver]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) 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/file-uploader/security/#secure-delivery-proxy) docs for details.

Attribute: `-`

DOM property: `secureDeliveryProxyUrlResolver`

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

Default: `null`

### groupOutput \[#group-output]

Enables files group creation.

Attribute: `group-output`

DOM property: `groupOutput`

Type: `boolean`

Default: `false`

If every file uploads but creating the group fails, the collection reports a
`GROUP_ERROR`, with the failure on `payload.error`. Handle it when you rely on
the group URL: the files exist, only the group is missing.

### retryThrottledRequestMaxTimes \[#retry-throttled-request-max-times]

Maximum number of retry attempts for throttled requests.

Attribute: `retry-throttled-request-max-times`

DOM property: `retryThrottledRequestMaxTimes`

Type: `number`

Default: `10`

### retryNetworkErrorMaxTimes \[#retry-network-error-max-times]

Maximum number of retry attempts for requests that failed due to network errors.

Attribute: `retry-network-error-max-times`

DOM property: `retryNetworkErrorMaxTimes`

Type: `number`

Default: `3`

### multipartMinFileSize \[#multipart-min-file-size]

Sets the file size threshold (in bytes) that triggers multipart upload mode instead of direct upload.

**Upload methods:**

* **Direct upload:** Files smaller than this threshold are uploaded in a single request
* **Multipart upload:** Files larger than this threshold are split into chunks and uploaded piece by piece

**Why this matters:**

* Multipart uploads are more reliable and faster for large files
* Direct uploads are faster for small files

Attribute: `multipart-min-file-size`

DOM property: `multipartMinFileSize`

Type: `number`

Default: `26214400` (25 MB)

### multipartChunkSize \[#multipart-chunk-size]

Defines the size (in bytes) of each chunk when uploading large files via multipart upload.

**How it works:** Large files are divided into smaller, manageable pieces of this size. Each chunk is uploaded independently, allowing for better error handling and speed.

**Tuning considerations:**

* **Larger chunks:** Fewer network requests, faster uploads
* **Smaller chunks:** More granular progress updates, better for unstable connections, but more network overhead

Attribute: `multipart-chunk-size`

DOM property: `multipartChunkSize`

Type: `number`

Default: `5242880` (5 MB)

### maxConcurrentRequests \[#max-concurrent-requests]

Controls the maximum number of files that can be uploaded simultaneously across the entire uploader instance.

This setting helps manage system resources and prevents overwhelming the user's network connection. Files exceeding this limit will be queued and processed once active uploads complete.

**Performance consideration:** Higher values increase upload speed but consume more bandwidth and system resources. Lower values reduce resource usage but may slow overall upload throughput.

**Example:** With `maxConcurrentRequests: 10`, if a user selects 20 files, only 10 will upload simultaneously while the remaining 10 wait in the queue.

Attribute: `max-concurrent-requests`

DOM property: `maxConcurrentRequests`

Type: `number`

Default: `10`

### multipartMaxConcurrentRequests \[#multipart-max-concurrent-requests]

Controls how many chunks can be uploaded simultaneously for each individual multipart upload.

When uploading large files (>25MB), they are split into smaller chunks. This setting limits how many of those chunks can be uploaded in parallel for each file.

**Example:** If set to `4`, only 4 chunks of a single multipart upload will be processed simultaneously, while remaining chunks wait in the queue.

Attribute: `multipart-max-concurrent-requests`

DOM property: `multipartMaxConcurrentRequests`

Type: `number`

Default: `4`

### multipartMaxAttempts \[#multipart-max-attempts]

Sets the maximum number of retry attempts for failed multipart upload chunks.

When a chunk fails to upload (due to network issues or server errors), the File Uploader will automatically retry uploading that specific chunk.

**Use case:** Increase this value for unreliable network conditions, or decrease it to fail faster in stable environments.

Attribute: `multipart-max-attempts`

DOM property: `multipartMaxAttempts`

Type: `number`

Default: `3`

### checkForUrlDuplicates \[#check-for-url-duplicates]

**Applies to URL uploads only.**

Enables duplicate URL detection to prevent uploading the same file multiple times from the same URL source.

When enabled, the system checks if a file from the given URL has already been uploaded. If a duplicate is found, it provides the existing file immediately instead of re-uploading, improving performance and reducing storage costs.

**Technical behavior:** Runs duplicate check first, then provides immediate-download behavior for existing files.

Attribute: `check-for-url-duplicates`

DOM property: `checkForUrlDuplicates`

Type: `boolean`

Default: `false`

### saveUrlForRecurrentUploads \[#save-url-for-recurrent-uploads]

**Applies to URL uploads only.**

Optimizes performance for frequently uploaded URLs by caching the source URL for future uploads.

This feature is beneficial when you expect the same URL to be uploaded multiple times. It not only saves the URL for faster subsequent uploads but also updates existing references when the source URL content changes.

**When to use:** Enable this when users frequently upload files from the same URLs (e.g., content management systems, recurring document uploads).

**Performance benefit:** Reduces upload time for repeated URLs and automatically handles content updates.

Attribute: `save-url-for-recurrent-uploads`

DOM property: `saveUrlForRecurrentUploads`

Type: `boolean`

Default: `false`

### metadata \[#metadata]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Defines custom metadata to be attached to uploaded files. This metadata is stored with the file and can be retrieved later via the Uploadcare API.

The metadata can be either:

* **Static object:** Fixed key-value pairs applied to all files
* **Dynamic function:** Computed per file based on file properties

**Function signature:** `(fileEntry: OutputFileEntry) => Promise<Record<string, string>> | Record<string, string>`

**Use cases:**

* Tagging files with categories, user IDs, or project names
* Adding custom processing flags
* Storing file-specific business logic data

Attribute: `-`

DOM property: `metadata`

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

Default: `null`

### tags \[#tags]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Defines [tags](/docs/file-tags/) to be attached to uploaded files. Tags are stored with the file and can be used to categorize and filter files later via the Uploadcare API.

Tags set via this property are not validated or normalized client-side; see [File tags](/docs/file-tags/) for the normalization rules and constraints (lowercase, trimmed, deduplicated, max 50 tags, max 100 chars, `[a-z0-9\-_.]` only) enforced by the Upload API.

The tags can be either:

* **Static array:** A fixed list of tag strings applied to all files
* **Dynamic function:** Computed per file based on file properties

**Function signature:** `(fileEntry: OutputFileEntry) => Promise<string[]> | string[]`

**Use cases:**

* Categorizing files by type, source, or workflow stage
* Attaching user IDs or project names to files
* Grouping files for later search and filtering

Attribute: `-`

DOM property: `tags`

Type: `string[] | ((fileEntry: OutputFileEntry) => Promise<string[]> | string[]) | null`

Default: `null`

### removeCopyright \[#remove-copyright]

Whitelabeling. Removes copyright.

Attribute: `remove-copyright`

DOM property: `removeCopyright`

This feature is available on some [paid plans](https://uploadcare.com/pricing/).

Type: `boolean`

Default: `false`

### debug \[#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 \[#locale-name]

Specifies the locale to use for localization.

See [Localization](/docs/file-uploader/localization/) for details.

Attribute: `locale-name`

DOM property: `localeName`

Type: `string`

Default: `"en"`

### localeDefinitionOverride \[#locale-definition-override]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

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

See [Localization](/docs/file-uploader/localization/) for details.

Attribute: `-`

DOM property: `localeDefinitionOverride`

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

Default: `{}`

### iconHrefResolver \[#icon-href-resolver]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) 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](/docs/file-uploader/styling/#icons) for details.

Attribute: `-`

DOM property: `iconHrefResolver`

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

Default: `null`

### fileValidators \[#file-validators]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Specify a file validators list.
See [File validators](/docs/file-uploader/file-validators) for details.

Attribute: `-`

DOM property: `fileValidators`

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

Default: `[]`

### validationTimeout \[#validation-timeout]

Sets the maximum time (in milliseconds) a single validator is allowed to run before it is aborted and skipped.

Use this to prevent long-running sync/async validators from blocking the UI if they hang or take too long. When the timeout is reached, the validator is cancelled via `AbortSignal` (for async validators) and its result is ignored.

See also: [File validators](/docs/file-uploader/file-validators)

Attribute: `validation-timeout`

DOM property: `validationTimeout`

Type: `number`

Default: `15000`

### validationConcurrency \[#validation-concurrency]

Limits how many files could be validated simultaneously.

Lower values reduce CPU usage and improve responsiveness on weaker devices; higher values validate faster for large selections.

See also: [File validators](/docs/file-uploader/file-validators)

Attribute: `validation-concurrency`

DOM property: `validationConcurrency`

Type: `number`

Default: `100`

### collectionValidators \[#collection-validators]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Specify a collection validators list.
See [Collection validators](/docs/file-uploader/collection-validators) for details.

Attribute: `-`

DOM property: `collectionValidators`

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

Default: `[]`

### enableAudioRecording \[#enable-audio-recording]

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

Attribute: `enable-audio-recording`

DOM property: `enableAudioRecording`

Type: `boolean`

Default: `true`

### enableVideoRecording (deprecated) \[#enable-video-recording]

> **Note**
>
> **Note:** This option is deprecated. Use [`cameraModes`](#camera-modes) instead.

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

Attribute: `enable-video-recording`

DOM property: `enableVideoRecording`

Type: `boolean`

Default: `true`

### maxVideoRecordingDuration \[#max-video-recording-duration]

Attribute: `max-video-recording-duration`

DOM property: `maxVideoRecordingDuration`

Type: `number`

Default: `null`

### cloudImageEditorMaskHref \[#cloud-image-editor-mask-href]

This property allows developers to define a custom overlay mask, specified as a URL, which can be applied within the editor interface.

Attribute: `cloud-image-editor-mask-href`

DOM property: `cloudImageEditorMaskHref`

Type: `string`

Default: `null`

### cameraModes \[#camera-modes]

Comma-separated list of camera recording modes. Order matters, the first mode will be selected by default.

Available values:

* `photo`: photo mode, default
* `video`: video mode

Attribute: `camera-modes`

DOM property: `cameraModes`

Type: `comma separated string`

Default: `'photo, video'`

### defaultCameraMode \[#default-camera-mode]

The default camera mode is to be selected when the camera is opened. If not set, the first mode from `cameraModes` will be used.

Attribute: `default-camera-mode`

DOM property: `defaultCameraMode`

Type: `string | null`

Available values:

* `photo`: photo mode
* `video`: video mode

Default: `null`

### filesViewMode \[#files-view-mode]

Defines the view mode for the file list.

Available values:

* `list`: list view mode
* `grid`: grid view mode

Attribute: `files-view-mode`

DOM property: `filesViewMode`

Default: `'list'`

### gridShowFileNames \[#grid-show-file-names]

Show file names in the grid view mode.

Attribute: `grid-show-file-names`

DOM property: `gridShowFileNames`

Type: `boolean`

Default: `false`

### cloudImageEditorAutoOpen \[#cloud-image-editor-auto-open]

Automatically open the cloud image editor when a single image is selected.

Attribute: `cloud-image-editor-auto-open`

DOM property: `cloudImageEditorAutoOpen`

Type: `boolean`

Default: `false`

### qualityInsights \[#quality-insights]

Quality insights collects non-personal usage data to help us understand how File Uploader is used and improve its quality

Attribute: `quality-insights`

DOM property: `qualityInsights`

Type: `boolean`

Default: `true`

### pasteScope \[#paste-scope]

Control how File Uploader handles clipboard paste events. This setting determines whether paste events are captured globally across the page or scoped to the File Uploader’s DOM subtree.

* `local`: listen only for paste events originating within the File Uploader’s DOM subtree. This prevents accidental uploads triggered elsewhere on the page.
* `global`: capture all paste events on the page and route clipboard files or URLs to the associated File Uploader instance.
* `false`: disable clipboard paste handling entirely.

Attribute: `paste-scope`

DOM property: `pasteScope`

Type: `local` | `global` | `false`

Default: `local`

### dynamicButtonViewMode \[#dynamic-button-view-mode]

Controls how Dynamic Button displays upload sources. This option applies when
`uc-file-uploader-regular` is used with the `dynamic-button` attribute.

* `auto`: shows secondary sources inline for up to three sources and switches
  to a dropdown menu when there are more.
* `menu`: shows the first source as the primary action and puts the remaining
  sources in a dropdown menu.
* `toolbar`: shows the first source as the primary action and the remaining
  sources inline.
* `compact`: shows a single paperclip-style menu button while idle and puts all
  sources in the menu.

Attribute: `dynamic-button-view-mode`

DOM property: `dynamicButtonViewMode`

Type: `auto` | `menu` | `toolbar` | `compact`

Default: `auto`

### dynamicButtonShowFirstIcon \[#dynamic-button-show-first-icon]

Shows the first source icon inside Dynamic Button's primary action while no files
are selected. This option applies when `uc-file-uploader-regular` is used with
the `dynamic-button` attribute.

Attribute: `dynamic-button-show-first-icon`

DOM property: `dynamicButtonShowFirstIcon`

Type: `boolean`

Default: `true`

### plugins \[#plugins]

Works as [DOM property](/docs/file-uploader/configuration/#how-to-define-dom-properties) only.

Plugins to register with the uploader. The uploader initializes them in array
order and skips duplicates by `id`. Assigning a new array resyncs the list: the
uploader disposes the plugins you removed and sets up the ones you added.

See [Plugin API](/docs/file-uploader/plugins/) docs for details.

Attribute: `-`

DOM property: `plugins`

Type: `UploaderPlugin[]`

Default: `[]`