Skip to navigation

File Uploader options

Here is a list of all available options for the File Uploader basic 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

Mirrors the camera view, and the photos and videos taken with it.

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'

Full source list:

  • local
  • url
  • camera
  • dropbox
  • gdrive
  • facebook
  • gphotos
  • box
  • onedrive

Custom upload sources can be added via the Plugin API.

topLevelOrigin

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

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

cloudImageEditorTabs

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

Attribute: cloud-image-editor-tabs

DOM property: cloudImageEditorTabs

Available values:

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' 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

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.

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

Set a custom upload URL.

Attribute: base-url

DOM property: baseUrl

Type: string

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

socialBaseUrl

Set a custom social sources URL.

Attribute: social-base-url

DOM property: socialBaseUrl

Type: string

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

authToken

A token for signed 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 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 this is an ordinary prop, function and all. On the web component, a function has to be set as a DOM property 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 covers issuing the tokens, and invalidateAuthToken() drops a cached one.

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

Set signature for signed uploads. See the signature reference for details, or authToken for the token scheme recommended for new integrations.

Attribute: secure-signature

DOM property: secureSignature

Type: string

Default: ''

secureExpire

Set expire for signed uploads. See the signature reference for details.

Attribute: secure-expire

DOM property: secureExpire

Type: string

Default: ''

secureUploadsSignatureResolver

Works as DOM property 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 and the signature reference 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 signed uploads expire value in milliseconds.

Note: This applies to signatures only. An authToken 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 and the signature reference 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

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

Maximum number of retry attempts for throttled requests.

Attribute: retry-throttled-request-max-times

DOM property: retryThrottledRequestMaxTimes

Type: number

Default: 10

retryNetworkErrorMaxTimes

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

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

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

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

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

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

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

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

Works as DOM property 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

Works as DOM property only.

Defines 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 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

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 File validators for details.

Attribute: -

DOM property: fileValidators

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

Default: []

validationTimeout

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

Attribute: validation-timeout

DOM property: validationTimeout

Type: number

Default: 15000

validationConcurrency

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

Attribute: validation-concurrency

DOM property: validationConcurrency

Type: number

Default: 100

collectionValidators

Works as DOM property only.

Specify a collection validators list. See Collection validators for details.

Attribute: -

DOM property: collectionValidators

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

Default: []

enableAudioRecording

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)

Note: This option is deprecated. Use cameraModes 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

Attribute: max-video-recording-duration

DOM property: maxVideoRecordingDuration

Type: number

Default: null

cloudImageEditorMaskHref

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

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

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

Camera settings in the camera screen

cameraAspectRatio, cameraResolution, cameraAudioQuality, and cameraAudioMode each take a single value or a comma-separated list. A list of two or more values adds a picker for that setting to the camera settings, opened with the settings button in the camera’s bottom bar. The picker starts on the first item, except the resolution picker, which starts on the first resolution the camera supports. The user’s pick applies to the open camera without reopening it, lasts only while the camera is open, and resets when the option changes in the config.

The settings also list the available cameras and, in video mode with audio recording on, the microphones, whenever there are two or more of them. These need no configuration.

<uc-config
ctx-name="my-uploader"
pubkey="YOUR_PUBLIC_KEY"
camera-aspect-ratio="1:1, native, 4:3"
camera-resolution="auto, 720p, 4k"
camera-audio-mode="voice, music"
></uc-config>

cameraAspectRatio

The shape of camera photos and videos, as "w:h": "1:1", "4:3", "16:9", "9:16", and so on. The ratio is taken literally whatever the device orientation. native or an empty value keeps the camera’s own shape.

Photos and videos are cropped to the largest centered rectangle of the ratio, and the preview shows the same crop. The ratio is also requested from the camera. When the camera can’t deliver it, videos are cropped frame by frame, which costs some CPU while recording.

A comma-separated list lets the user pick in the camera screen, starting on the first item.

Attribute: camera-aspect-ratio

DOM property: cameraAspectRatio

Type: string

Default: ''

Example: '1:1' or '1:1, native, 4:3'

cameraResolution

The resolution requested from the camera, for both photo and video.

  • auto: a 1080 px short side in the cameraAspectRatio shape, or 1920×1080 without a ratio.
  • 720p, 1080p, 4k: a short side of 720, 1080, or 2160 px. The long side follows cameraAspectRatio, or 16:9 without a ratio.

The camera picks its closest supported resolution, so the value is a request, not a guarantee.

A comma-separated list lets the user pick in the camera screen, starting on the first item the camera supports. Presets above what the camera reports are left out.

Note: Large resolutions make big video files, which may exceed maxLocalFileSizeBytes.

Attribute: camera-resolution

DOM property: cameraResolution

Type: string

Default: 'auto'

Example: '1080p' or 'auto, 720p, 4k'

cameraPhotoQuality

The JPEG quality of camera photos, from 0 to 1.

Attribute: camera-photo-quality

DOM property: cameraPhotoQuality

Type: number

Default: 0.92

cameraVideoFormats

Video formats to record in, best first, as a comma-separated list. The first format the browser can record wins. When nothing listed is supported, the browser picks.

Available values:

  • webm: WebM.
  • mp4: MP4, with H.264 and AAC where the browser supports them.
  • A MIME type with a single codec, such as video/webm;codecs=vp9. A codec list doesn’t work here, since its commas would split the list.

For an exact codec list, set mimeType in mediaRecorderOptions. It takes precedence when the browser supports it.

Attribute: camera-video-formats

DOM property: cameraVideoFormats

Type: comma separated string

Default: 'webm, mp4'

Example: 'mp4, webm'

cameraAudioQuality

The audio bitrate of video recordings.

  • auto: the browser decides.
  • low: 32 kbps.
  • standard: 96 kbps.
  • high: 192 kbps.

An explicit audioBitsPerSecond or bitsPerSecond in mediaRecorderOptions takes precedence.

A comma-separated list lets the user pick in the camera screen, in video mode with audio recording on, starting on the first item.

Attribute: camera-audio-quality

DOM property: cameraAudioQuality

Type: string

Default: 'auto'

Example: 'high' or 'auto, low, high'

cameraAudioMode

How the microphone is set up for video recordings.

  • voice: the browser defaults for speech, usually mono with echo cancellation, noise suppression, and auto gain.
  • music: stereo where the microphone supports it, with that processing off.

audio in cameraConstraints overrides it setting by setting. A change reopens only the microphone, and the camera keeps running. During a recording, the change waits until the recording stops.

A comma-separated list lets the user pick in the camera screen, in video mode with audio recording on, starting on the first item.

Attribute: camera-audio-mode

DOM property: cameraAudioMode

Type: string

Default: 'voice'

Example: 'music' or 'voice, music'

cameraConstraints

Works as DOM property only.

Extra getUserMedia constraints for the camera and microphone, as an object or as a function of the active camera mode.

Each property replaces the built-in value of the same name (width, height, frameRate, and so on). The camera and microphone picked in the camera screen always win over deviceId.

The constraints are re-applied when the option changes or, for the function form, when the user switches between photo and video. Video constraints apply to the open camera, and audio constraints reopen only the microphone. Changes made during a recording apply once it stops.

Note: If the camera can’t satisfy the constraints, it opens without them and logs a warning to the console.
const config = document.querySelector('uc-config');
config.cameraConstraints = ({ mode }) => ({
video: mode === 'video' ? { frameRate: { ideal: 60 } } : { facingMode: 'environment' },
});

Attribute: -

DOM property: cameraConstraints

Type: { video?: MediaTrackConstraints; audio?: MediaTrackConstraints } | (({ mode }: { mode: 'photo' | 'video' }) => { video?: MediaTrackConstraints; audio?: MediaTrackConstraints }) | null

Default: null

mediaRecorderOptions

Works as DOM property only.

Options passed to the browser’s MediaRecorder for video recordings. A supported mimeType takes precedence over cameraVideoFormats, and audioBitsPerSecond or bitsPerSecond take precedence over cameraAudioQuality.

Attribute: -

DOM property: mediaRecorderOptions

Type: MediaRecorderOptions | null

Default: null

filesViewMode

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

Show file names in the grid view mode.

Attribute: grid-show-file-names

DOM property: gridShowFileNames

Type: boolean

Default: false

cloudImageEditorAutoOpen

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

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

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

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

Works as DOM property 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 for details.

Attribute: -

DOM property: plugins

Type: UploaderPlugin[]

Default: []