Configuration Options

The File Uploader can be configured using various options that control upload behavior, validation, UI appearance, and more. This page provides a complete reference for all available configuration options.

Basic Configuration

pubkey

string

required

Your project’s Public Key. This is required to use the File Uploader.Default: ''

multiple

boolean

Allow multiple file uploads.Default: true

<uc-config pubkey="YOUR_PUBLIC_KEY" multiple="true"></uc-config>

multipleMin

number

Minimum number of files to upload.Default: 0

multipleMax

number

Maximum number of files to upload.Default: Number.MAX_SAFE_INTEGER

<uc-config pubkey="YOUR_PUBLIC_KEY" multiple-max="10"></uc-config>

confirmUpload

boolean

Require user confirmation before uploading.Default: false

groupOutput

boolean

Group output files. When enabled, multiple files will be combined into a single group.Default: false

File Validation

imgOnly

boolean

Allow only image files.Default: false

<uc-config pubkey="YOUR_PUBLIC_KEY" img-only="true"></uc-config>

string

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

<uc-config accept="image/*,.pdf"></uc-config>

maxLocalFileSizeBytes

number

Maximum size of local files in bytes. Set to 0 for no limit.Default: 0

<uc-config max-local-file-size-bytes="10485760"></uc-config>

fileValidators

FileValidators

Validators for individual files. This is an array of file validator functions.Default: []

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.fileValidators = [
  (file) => {
    if (file.size > 1000000) {
      return { message: 'File is too large' };
    }
  }
];

collectionValidators

CollectionValidators

Validators for file collections. This is an array of collection validator functions.Default: []

This is a complex type that must be set via JavaScript, not as an HTML attribute.

validationTimeout

number

Timeout for async validation functions, in milliseconds.Default: 15000 (15 seconds)

validationConcurrency

number

The number of files to validate concurrently.Default: 100

Upload Sources

sourceList

string

List of sources for file uploads. Comma-separated list of source names.Default: 'local, url, camera, dropbox, gdrive'Available sources:

local - Local file system
url - URL import
camera - Camera capture
dropbox - Dropbox
gdrive - Google Drive
gphotos - Google Photos
instagram - Instagram
facebook - Facebook
flickr - Flickr
vk - VK
evernote - Evernote
box - Box
onedrive - OneDrive
huddle - Huddle

<uc-config source-list="local, url, camera"></uc-config>

sourceListWrap

boolean

Wrap the source list when it overflows.Default: true

externalSourcesPreferredTypes

string

Preferred types for external sources. This affects which file types are displayed first in external source pickers.Default: ''See External Sources Preferred Types for more details.

externalSourcesEmbedCss

string

Provide custom CSS to the social sources iframe.Default: ''

remoteTabSessionKey

string

Key to revoke Custom OAuth access. See OAuth docs for details.Default: ''

topLevelOrigin

string

Top-level origin for the uploader. This is used for Google Drive Picker if there is no access to the origin due to the cross-origin policy.Default: ''

Camera Configuration

cameraCapture

'user' | 'environment' | ''

Default camera capture mode. Determines which camera is used by default.Default: ''

'user' - Front-facing camera
'environment' - Back-facing camera
'' - Browser default

cameraMirror

boolean

Mirror the camera view horizontally.Default: false

cameraModes

string

The camera modes to enable in the camera modal. It is possible to select photo or video capture. The first mode is the default mode.Default: 'photo, video'

<uc-config camera-modes="photo"></uc-config>

defaultCameraMode

'photo' | 'video' | null

The default tab to open in the camera modal.Default: null

Deprecated: Use cameraModes instead.

enableAudioRecording

boolean

Enable audio recording in the camera modal.Default: true

enableVideoRecording

boolean | null

Enable video recording.Default: null

Deprecated: Use cameraModes instead.

maxVideoRecordingDuration

number | null

The maximum duration of the video recording in seconds. Set to null for no limit.Default: null

mediaRecorderOptions

MediaRecorderOptions | null

A dictionary object that can contain properties from MediaRecorderOptions.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.mediaRecorderOptions = {
  mimeType: 'video/webm;codecs=vp9',
  videoBitsPerSecond: 2500000
};

Storage & CDN

store

boolean | 'auto'

Store uploaded files permanently.Default: 'auto'

true - Files are stored permanently
false - Files are stored temporarily (24 hours)
'auto' - Uses your project’s default storage setting

cdnCname

string

Set custom CNAME for CDN URLs.Default: 'https://ucarecdn.com'

cdnCnamePrefixed

string

Set CNAME base domain for prefixed CDN URLs.Default: 'https://ucarecd.net'

Upload Configuration

baseUrl

string

Set a custom upload URL.Default: 'https://upload.uploadcare.com'

Set a custom social sources URL.Default: 'https://social.uploadcare.com'

maxConcurrentRequests

number

Maximum number of concurrent upload requests.Default: 10

retryThrottledRequestMaxTimes

number

Maximum number of retry attempts for throttled requests.Default: 3

retryNetworkErrorMaxTimes

number

Maximum number of retry attempts for network errors.Default: 3

checkForUrlDuplicates

boolean

Check for URL duplicates before uploading.Default: false

saveUrlForRecurrentUploads

boolean

Save URL for recurrent uploads to avoid re-uploading the same file.Default: false

Multipart Uploads

multipartMinFileSize

number

Minimum file size in bytes for multipart uploads. Files larger than this will be uploaded in chunks.Default: 26214400 (25 MB)

multipartChunkSize

number

Chunk size for multipart uploads in bytes.Default: 5242880 (5 MB)

multipartMaxConcurrentRequests

number

Maximum number of concurrent requests for multipart uploads.Default: 4

multipartMaxAttempts

number

Maximum number of attempts for multipart upload chunks.Default: 3

Security

secureSignature

string

Secure signature for uploads. Used for signed uploads to prevent unauthorized file uploads.Default: ''See Signed Uploads for more details.

secureExpire

string

Expiry time for secure uploads. Unix timestamp as a string.Default: ''

secureUploadsExpireThreshold

number

Expiry threshold for secure uploads in milliseconds. When the signature is about to expire within this threshold, the resolver will be called again.Default: 600000 (10 minutes)

secureUploadsSignatureResolver

SecureUploadsSignatureResolver | null

Resolver function for secure uploads signature. Returns a promise that resolves to an object containing secureSignature and secureExpire.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.secureUploadsSignatureResolver = async () => {
  const response = await fetch('/get-uploadcare-signature');
  const { signature, expire } = await response.json();
  return {
    secureSignature: signature,
    secureExpire: expire
  };
};

secureDeliveryProxy

string

Proxy URL for secure delivery.Default: ''

secureDeliveryProxyUrlResolver

SecureDeliveryProxyUrlResolver | null

Resolver function for secure delivery proxy URL.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.secureDeliveryProxyUrlResolver = async (previewUrl, { uuid, cdnUrlModifiers, fileName }) => {
  return `https://your-proxy.com/${uuid}/${cdnUrlModifiers}/${fileName}`;
};

Image Processing

cropPreset

string

Defines the crop behavior. When uploading images, your users can select a crop area with a defined aspect ratio.Default: ''Examples: '1:1', '16:9', 'free'

imageShrink

string

Image shrink options. Automatically resize images before upload.Default: ''Example: '1024x1024' to resize images larger than 1024x1024 pixels.

useLocalImageEditor

boolean

Use local image editor for basic image editing operations.Default: false

useCloudImageEditor

boolean

Enable cloud image editing with advanced features.Default: true

cloudImageEditorTabs

string

Tabs to show in the cloud image editor. Comma-separated list.Default: 'crop, tuning, filters'Available tabs:

crop - Crop and rotate
tuning - Brightness, contrast, saturation, etc.
filters - Apply filters
blur - Blur effects
sharp - Sharpen
enhance - Auto-enhance

cloudImageEditorAutoOpen

boolean

Automatically open the cloud image editor after selecting an image.Default: false

cloudImageEditorMaskHref

string | null

URL to a mask image for the cloud image editor.Default: null

qualityInsights

boolean

Enable quality insights for uploaded images. Shows warnings about image quality issues.Default: true

removeCopyright

boolean

Remove copyright information from images.Default: false

UI Configuration

thumbSize

number

Thumbnail size in pixels.Default: 76

showEmptyList

boolean

Show the upload list even if it is empty.Default: false

filesViewMode

'grid' | 'list'

Display mode for the files list.Default: 'list'

'list' - Show files in a list view
'grid' - Show files in a grid view

gridShowFileNames

boolean

Show file names in grid view mode.Default: false

Lock scroll when modal is open. Prevents scrolling of the page behind the modal.Default: true

Show animated strokes on modal backdrop for a more engaging appearance.Default: false

Localization

localeName

string

Locale name for the uploader. Determines the language of the UI.Default: 'en'Supported locales:

'en' - English
'ar' - Arabic
'az' - Azerbaijani
'ca' - Catalan
'cs' - Czech
'da' - Danish
'de' - German
'el' - Greek
'es' - Spanish
'et' - Estonian
'fr' - French
'he' - Hebrew
'it' - Italian
'ja' - Japanese
'ko' - Korean
'lv' - Latvian
'nb' - Norwegian Bokmål
'nl' - Dutch
'pl' - Polish
'pt' - Portuguese
'ro' - Romanian
'ru' - Russian
'sk' - Slovak
'sr' - Serbian
'sv' - Swedish
'tr' - Turkish
'uk' - Ukrainian
'vi' - Vietnamese
'zh' - Chinese
'zh-TW' - Chinese (Taiwan)

<uc-config locale-name="es"></uc-config>

localeDefinitionOverride

LocaleDefinitionOverride | null

Override locale definitions. Allows customizing translation strings.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.localeDefinitionOverride = {
  en: {
    'upload-file': 'Select File',
    'upload-files': 'Select Files'
  }
};

Metadata

metadata

Metadata | MetadataCallback | null

Metadata for uploaded files. Can be a static object or a callback function that returns metadata for each file.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

// Static metadata for all files
const config = document.querySelector('uc-config');
config.metadata = {
  userId: '12345',
  source: 'web-app'
};

// Dynamic metadata per file
config.metadata = async (fileEntry) => {
  return {
    fileName: fileEntry.name,
    uploadedAt: new Date().toISOString()
  };
};

Advanced Configuration

iconHrefResolver

IconHrefResolver | null

Resolver function for icon href. Allows customizing icon URLs.Default: null

This is a complex type that must be set via JavaScript, not as an HTML attribute.

const config = document.querySelector('uc-config');
config.iconHrefResolver = (iconName) => {
  return `/custom-icons/${iconName}.svg`;
};

userAgentIntegration

string

User agent integration string. Used to identify the integration in analytics.Default: ''

pasteScope

'local' | 'global' | false

Define the clipboard paste scope.Default: 'local'

'local' - Paste is only active when the uploader is focused
'global' - Paste is active anywhere on the page
false - Paste is disabled

testMode

boolean

Adds data-testid attributes to each block. Needed for testing purposes.Default: false

debug

boolean

Enable debug mode. Outputs detailed logs to the console.Default: false

<uc-config debug="true"></uc-config>

Configuration Methods

Setting Options via HTML Attributes

Simple configuration options can be set directly as HTML attributes. Use kebab-case for attribute names:

<uc-config
  pubkey="YOUR_PUBLIC_KEY"
  multiple="true"
  multiple-max="10"
  img-only="false"
  max-local-file-size-bytes="10485760"
></uc-config>

Setting Options via JavaScript

Complex options (objects, functions, arrays) must be set via JavaScript:

const config = document.querySelector('uc-config');

// Set simple options
config.multiple = true;
config.multipleMax = 10;

// Set complex options
config.metadata = { userId: '12345' };
config.fileValidators = [
  (file) => {
    if (file.size > 1000000) {
      return { message: 'File is too large' };
    }
  }
];

Setting Options in Frameworks

React
Vue
Angular

import { FileUploaderRegular } from '@uploadcare/react-uploader';

function App() {
  const handleMetadata = (fileEntry) => {
    return {
      fileName: fileEntry.name,
      uploadedAt: new Date().toISOString()
    };
  };
  
  return (
    <FileUploaderRegular
      pubkey="YOUR_PUBLIC_KEY"
      multiple={true}
      multipleMax={10}
      metadata={handleMetadata}
    />
  );
}

<template>
  <file-uploader-regular
    :pubkey="pubkey"
    :multiple="true"
    :multiple-max="10"
    :metadata="handleMetadata"
  />
</template>

<script>
import { FileUploaderRegular } from '@uploadcare/vue-uploader';

export default {
  components: {
    FileUploaderRegular
  },
  data() {
    return {
      pubkey: 'YOUR_PUBLIC_KEY'
    };
  },
  methods: {
    handleMetadata(fileEntry) {
      return {
        fileName: fileEntry.name,
        uploadedAt: new Date().toISOString()
      };
    }
  }
};
</script>

import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `
    <file-uploader-regular
      [pubkey]="pubkey"
      [multiple]="true"
      [multipleMax]="10"
      [metadata]="handleMetadata"
    ></file-uploader-regular>
  `
})
export class AppComponent {
  pubkey = 'YOUR_PUBLIC_KEY';
  
  handleMetadata = (fileEntry: any) => {
    return {
      fileName: fileEntry.name,
      uploadedAt: new Date().toISOString()
    };
  };
}

Type Definitions

FileValidator

type FuncFileValidator = (
  fileEntry: OutputFileEntry
) => OutputError<OutputFileErrorType> | void | Promise<OutputError<OutputFileErrorType> | void>;

type FileValidatorDescriptor = {
  type: OutputFileErrorType;
  validator: FuncFileValidator;
};

type FileValidator = FuncFileValidator | FileValidatorDescriptor;
type FileValidators = FileValidator[];

CollectionValidator

type FuncCollectionValidator = (
  collection: OutputFileEntry[]
) => OutputError<OutputCollectionErrorType> | void | Promise<OutputError<OutputCollectionErrorType> | void>;

type CollectionValidators = FuncCollectionValidator[];

MetadataCallback

type Metadata = Record<string, string>;

type MetadataCallback = (
  fileEntry: OutputFileEntry
) => Promise<Metadata> | Metadata;

SecureUploadsSignatureResolver

type SecureUploadsSignatureAndExpire = {
  secureSignature: string;
  secureExpire: string;
};

type SecureUploadsSignatureResolver = () => Promise<SecureUploadsSignatureAndExpire | null>;

SecureDeliveryProxyUrlResolver

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

IconHrefResolver

type IconHrefResolver = (iconName: string) => string;

LocaleDefinitionOverride

type LocaleDefinitionOverride = Record<string, Partial<LocaleDefinition>>;

Best Practices

Use Auto Store for Production

Set store to 'auto' to use your project’s default storage setting. This makes it easier to manage storage behavior across different environments.

<uc-config store="auto"></uc-config>

Validate Files Early

Use fileValidators to validate files before they’re uploaded. This provides immediate feedback to users and reduces unnecessary upload traffic.

config.fileValidators = [
  (file) => {
    // Check file size
    if (file.size > 5 * 1024 * 1024) {
      return { message: 'File must be smaller than 5MB' };
    }
    
    // Check file type
    if (!file.mimeType.startsWith('image/')) {
      return { message: 'Only images are allowed' };
    }
  }
];

Use Secure Uploads for Sensitive Applications

Implement secure uploads using secureUploadsSignatureResolver to prevent unauthorized file uploads.

config.secureUploadsSignatureResolver = async () => {
  const response = await fetch('/api/uploadcare-signature');
  return await response.json();
};

Optimize Multipart Upload Settings

Adjust multipart upload settings based on your users’ typical connection speeds. For users with slower connections, consider using smaller chunk sizes.

<uc-config
  multipart-min-file-size="10485760"
  multipart-chunk-size="2097152"
></uc-config>

Customize Source List

Only include the upload sources that your users actually need. This simplifies the UI and improves the user experience.

<uc-config source-list="local, camera, url"></uc-config>

Add Metadata for Organization

Use the metadata option to attach custom data to uploaded files. This helps with organizing and tracking files in your application.

config.metadata = {
  userId: currentUser.id,
  context: 'profile-photo',
  uploadedFrom: 'web-app'
};

Configuration

Types

API

Basic Configuration

File Validation

Upload Sources

Camera Configuration

Storage & CDN

Upload Configuration

Multipart Uploads

Security

Image Processing

UI Configuration

Localization

Metadata

Advanced Configuration

Configuration Methods

Setting Options via HTML Attributes

Setting Options via JavaScript

Setting Options in Frameworks

Type Definitions

FileValidator

CollectionValidator

MetadataCallback

SecureUploadsSignatureResolver

SecureDeliveryProxyUrlResolver

IconHrefResolver

LocaleDefinitionOverride

Best Practices

Build docs developers (and LLMs) love

Configuration

Types

API

​Basic Configuration

​File Validation

​Upload Sources

​Camera Configuration

​Storage & CDN

​Upload Configuration

​Multipart Uploads

​Security

​Image Processing

​UI Configuration

​Localization

​Metadata

​Advanced Configuration

​Configuration Methods

​Setting Options via HTML Attributes

​Setting Options via JavaScript

​Setting Options in Frameworks

​Type Definitions

​FileValidator

​CollectionValidator

​MetadataCallback

​SecureUploadsSignatureResolver

​SecureDeliveryProxyUrlResolver

​IconHrefResolver

​LocaleDefinitionOverride

​Best Practices

​Related Resources

Build docs developers (and LLMs) love

Basic Configuration

File Validation

Upload Sources

Camera Configuration

Storage & CDN

Upload Configuration

Multipart Uploads

Security

Image Processing

UI Configuration

Localization

Metadata

Advanced Configuration

Configuration Methods

Setting Options via HTML Attributes

Setting Options via JavaScript

Setting Options in Frameworks

Type Definitions

FileValidator

CollectionValidator

MetadataCallback

SecureUploadsSignatureResolver

SecureDeliveryProxyUrlResolver

IconHrefResolver

LocaleDefinitionOverride

Best Practices

Related Resources