Skip to main content
The Config component is the central configuration hub for Uploadcare File Uploader. It accepts configuration options as HTML attributes or DOM properties and synchronizes them with the shared state across all components.

​
Overview

The Config component extends LitBlock and provides a reactive configuration system. All configuration values can be set via:
  • HTML attributes (kebab-case or lowercase)
  • DOM properties (camelCase)
  • JavaScript API
Changes to configuration are automatically propagated to all connected components in the same context.

​
Basic Usage

<uc-config 
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  multiple
  max-local-file-size-bytes="52428800"
  source-list="local, url, camera"
></uc-config>

​
Configuration via Properties

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

// Set properties programmatically
config.pubkey = 'YOUR_PUBLIC_KEY';
config.multiple = true;
config.multipleMax = 10;
config.sourceList = 'local, url, camera, dropbox';

​
Core Properties

​
Upload Settings

​
pubkey
string
required
Your Uploadcare public key. Required for the uploader to work.
<uc-config pubkey="demopublickey"></uc-config>
​
multiple
boolean
default:"true"
Allow multiple file uploads.
<uc-config multiple></uc-config>
​
multipleMin
number
default:"0"
Minimum number of files required.
<uc-config multiple-min="1"></uc-config>
​
multipleMax
number
default:"Infinity"
Maximum number of files allowed.
<uc-config multiple-max="5"></uc-config>
​
confirmUpload
boolean
default:"false"
Require manual confirmation before uploading files.
<uc-config confirm-upload></uc-config>

​
File Restrictions

​
imgOnly
boolean
default:"false"
Accept only image files.
<uc-config img-only></uc-config>
​
accept
string
default:""
Specify accepted file types (MIME types or extensions).
<uc-config accept="image/*,.pdf"></uc-config>
​
maxLocalFileSizeBytes
number
default:"0"
Maximum file size in bytes. 0 means no limit.
<uc-config max-local-file-size-bytes="52428800"></uc-config>

​
Upload Sources

​
sourceList
string
default:"'local, url, camera, dropbox, gdrive'"
Comma-separated list of available upload sources.Available sources: local, url, camera, dropbox, gdrive, gphotos, instagram, facebook, onedrive, box, vk, evernote, flickr, unsplash
<uc-config source-list="local, url, camera"></uc-config>

​
Camera Settings

​
cameraMirror
boolean
default:"false"
Mirror the camera preview.
<uc-config camera-mirror></uc-config>
​
cameraModes
string
default:"'photo, video'"
Available camera modes (comma-separated).
<uc-config camera-modes="photo, video"></uc-config>
​
enableAudioRecording
boolean
default:"true"
Enable audio recording in video mode.
<uc-config enable-audio-recording="false"></uc-config>
​
maxVideoRecordingDuration
number
default:"null"
Maximum video recording duration in seconds. null means no limit.
<uc-config max-video-recording-duration="60"></uc-config>

​
Storage & CDN

​
store
string
default:"'auto'"
File storage mode. Can be 'auto', '1' (store), or '0' (don’t store).
<uc-config store="1"></uc-config>
​
cdnCname
string
default:"'https://ucarecdn.com'"
Custom CDN CNAME for file delivery.
<uc-config cdn-cname="https://cdn.example.com"></uc-config>

​
UI Settings

​
modalScrollLock
boolean
default:"true"
Lock body scroll when modal is open.
<uc-config modal-scroll-lock="false"></uc-config>
​
showEmptyList
boolean
default:"false"
Show upload list even when empty.
<uc-config show-empty-list></uc-config>
​
filesViewMode
string
default:"'list'"
Display mode for files. Can be 'list' or 'grid'.
<uc-config files-view-mode="grid"></uc-config>

​
Localization

​
localeName
string
default:"'en'"
Locale code for UI text.
<uc-config locale-name="es"></uc-config>

​
Advanced Settings

​
debug
boolean
default:"false"
Enable debug mode with console logging.
<uc-config debug></uc-config>
​
groupOutput
boolean
default:"false"
Group uploaded files into a single CDN group.
<uc-config group-output></uc-config>

​
Complex Properties

Some configuration options cannot be set as attributes and must be set via JavaScript properties:

​
metadata

Custom metadata to attach to uploaded files. 
config.metadata = {
  userId: '12345',
  sessionId: 'abc-def',
};

​
fileValidators

Array of custom validation functions for files. 
config.fileValidators = [
  (fileInfo) => {
    if (fileInfo.size > 10 * 1024 * 1024) {
      return 'File is too large';
    }
  },
];

​
collectionValidators

Array of custom validation functions for the entire file collection. 
config.collectionValidators = [
  (collection) => {
    if (collection.length === 0) {
      return 'Please select at least one file';
    }
  },
];

​
secureUploadsSignatureResolver

Function to resolve secure upload signatures. 
config.secureUploadsSignatureResolver = async (fileInfo) => {
  const response = await fetch('/api/upload-signature', {
    method: 'POST',
    body: JSON.stringify({ filename: fileInfo.name }),
  });
  const data = await response.json();
  return data.signature;
};

​
mediaRecorderOptions

Options for the MediaRecorder API when recording video. 
config.mediaRecorderOptions = {
  mimeType: 'video/webm;codecs=vp9',
  videoBitsPerSecond: 2500000,
};

​
Context Sharing

The ctx-name attribute connects Config with other components: 
<uc-config ctx-name="my-uploader" pubkey="demopublickey"></uc-config>
<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>
<uc-drop-area ctx-name="my-uploader"></uc-drop-area>
All components with the same ctx-name share the same configuration and state.

​
Attribute Mapping

Attributes can be written in different formats:
  • Kebab-case: max-local-file-size-bytes="1000000"
  • Lowercase: maxlocalfilesizebytes="1000000"
  • Property (camelCase): element.maxLocalFileSizeBytes = 1000000

​
Reactive Updates

Configuration changes trigger automatic updates across the uploader: 
const config = document.querySelector('uc-config');

// This change will immediately affect all components
config.sourceList = 'local, url';

​
Source Code Reference

Implementation: /workspace/source/src/blocks/Config/Config.ts:55 Initial configuration values: /workspace/source/src/blocks/Config/initialConfig.ts:10

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us