Skip to main content
The File Uploader uses a powerful configuration system that allows you to customize every aspect of the uploader’s behavior. Configuration is handled through the Config block, which manages options via attributes, properties, and reactive state.

​
How Configuration Works

Configuration in the File Uploader follows a reactive architecture:
  1. Configuration options are defined with default values
  2. Changes propagate through the component tree automatically
  3. Computed properties derive values from other configuration options
  4. Validation ensures configuration consistency

​
The Config Block

The Config block is a special component that acts as the central configuration hub: 
import { Config } from '@uploadcare/file-uploader';

// Config automatically syncs between:
// - DOM attributes (kebab-case)
// - JavaScript properties (camelCase)
// - Internal state
From src/blocks/Config/Config.ts:55-65: 
export class Config extends LitBlock {
  public override init$ = {
    ...this.init$,
    ...Object.fromEntries(
      Object.entries(initialConfig).map(([key, value]) => 
        [sharedConfigKey(key as keyof ConfigType), value]
      ),
    ),
  } as unknown as LitBlock['init$'] & ConfigType;
}

​
Configuration Options

​
Basic Options

These are the fundamental configuration options for the uploader:

pubkey

Your project’s Public Key (required)
pubkey: 'your_public_key'

multiple

Allow multiple file uploads
multiple: true

imgOnly

Restrict uploads to images only
imgOnly: false

store

Control file storage behavior
store: 'auto' // or true/false

​
Upload Sources

Control which upload sources are available: 
sourceList: 'local, url, camera, dropbox, gdrive'
Available sources:
  • local - Local file system
  • url - Upload from URL
  • camera - Camera/webcam capture
  • dropbox - Dropbox integration
  • gdrive - Google Drive integration
  • Plus more external sources
From src/blocks/Config/initialConfig.ts:24: 
sourceList: 'local, url, camera, dropbox, gdrive',

​
File Size and Type Restrictions

{
  maxLocalFileSizeBytes: 0, // 0 means no limit
  accept: '', // MIME types or extensions
  multipleMin: 0,
  multipleMax: Number.MAX_SAFE_INTEGER
}

​
Upload Behavior

{
  confirmUpload: false, // Require user confirmation
  multipartMinFileSize: 26214400, // 25 MB
  multipartChunkSize: 5242880, // 5 MB
  maxConcurrentRequests: 10,
  multipartMaxConcurrentRequests: 4,
  retryThrottledRequestMaxTimes: 3,
  retryNetworkErrorMaxTimes: 3
}

​
Image Editing

{
  useCloudImageEditor: true,
  cloudImageEditorTabs: 'crop, tuning, filters',
  cloudImageEditorAutoOpen: false,
  useLocalImageEditor: false,
  cropPreset: '', // e.g., '1:1' or '16:9'
  imageShrink: ''
}

​
Camera Options

From src/blocks/Config/initialConfig.ts:22-23 and 75-80: 
{
  cameraMirror: false,
  cameraCapture: '', // 'user' or 'environment'
  cameraModes: 'photo, video',
  defaultCameraMode: null,
  enableAudioRecording: true,
  enableVideoRecording: null,
  maxVideoRecordingDuration: null
}

​
Plain vs Complex Configuration

Configuration options are divided into two categories:

​
Plain Configuration

Options that can be set via HTML attributes (strings, numbers, booleans): 
<uc-config
  pubkey="your_key"
  multiple="true"
  max-local-file-size-bytes="52428800"
  source-list="local, url, camera"
></uc-config>

​
Complex Configuration

Options that require objects or functions (must be set via JavaScript): From src/blocks/Config/Config.ts:20-29: 
export const complexConfigKeys = [
  'metadata',
  'localeDefinitionOverride',
  'secureUploadsSignatureResolver',
  'secureDeliveryProxyUrlResolver',
  'iconHrefResolver',
  'fileValidators',
  'collectionValidators',
  'mediaRecorderOptions',
] as const;

​
Metadata

Attach custom metadata to uploaded files: 
config.metadata = {
  userId: '12345',
  source: 'web-app'
};

// Or use a callback for dynamic metadata
config.metadata = (fileEntry) => {
  return {
    fileName: fileEntry.name,
    uploadedAt: new Date().toISOString()
  };
};

​
File Validators

Add custom validation rules: 
config.fileValidators = [
  (fileEntry) => {
    if (fileEntry.size > 10 * 1024 * 1024) {
      return { message: 'File too large (max 10MB)' };
    }
  }
];

​
Secure Uploads

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

​
Computed Properties

Some configuration options are automatically computed based on other options. From src/blocks/Config/computed-properties.ts:33-48: 
defineComputedProperty({
  key: 'cameraModes',
  deps: ['enableVideoRecording'] as const,
  fn: ({ cameraModes, enableVideoRecording }) => {
    if (enableVideoRecording === null) {
      return cameraModes;
    }
    let cameraModesCsv = deserializeCsv(cameraModes);
    if (enableVideoRecording && !cameraModesCsv.includes('video')) {
      cameraModesCsv = cameraModesCsv.concat('video');
    } else if (!enableVideoRecording) {
      cameraModesCsv = cameraModesCsv.filter((mode) => mode !== 'video');
    }
    return serializeCsv(cameraModesCsv);
  },
})
This means when you set enableVideoRecording, the cameraModes option updates automatically.

​
Setting Configuration

​
Via HTML Attributes

<uc-file-uploader-regular
  pubkey="your_public_key"
  multiple="true"
  source-list="local, camera"
  max-local-file-size-bytes="52428800"
>
</uc-file-uploader-regular>

​
Via JavaScript Properties

const uploader = document.querySelector('uc-file-uploader-regular');

uploader.pubkey = 'your_public_key';
uploader.multiple = true;
uploader.sourceList = 'local, camera';

​
Via uc-config Block

<uc-file-uploader-regular>
  <uc-config
    ctx-name="my-uploader"
    pubkey="your_public_key"
    multiple="true"
  ></uc-config>
</uc-file-uploader-regular>

​
Programmatic Access

const uploader = document.querySelector('uc-file-uploader-regular');
const api = uploader.getAPI();

// Read configuration
console.log(api.cfg.multiple);

// Modify configuration
api.cfg.multiple = false;

​
Configuration Context

Configuration is shared across all components in the same context using a reactive state system:
All components within a solution automatically share the same configuration context. Changes to configuration propagate immediately to all components.
From src/blocks/Config/Config.ts:83-92: 
private _flushValueToState<TKey extends keyof ConfigType>(
  key: TKey, 
  value: unknown
) {
  if (this.$[sharedConfigKey(key)] !== value) {
    if (typeof value === 'undefined' || value === null) {
      this.$[sharedConfigKey(key)] = initialConfig[key];
    } else {
      this.$[sharedConfigKey(key)] = value;
    }
  }
}

​
Debug Mode

Enable debug mode to see configuration changes in the console: 
config.debug = true;
This will log all configuration changes with detailed information.

​
Best Practices

Set all configuration options before the uploader initializes to avoid multiple reconfigurations.
When using TypeScript, leverage the type definitions to ensure configuration correctness.
Always test custom file validators thoroughly to ensure they handle edge cases.
When updating complex configuration like metadata or validators, create new objects rather than mutating existing ones.

​
Next Steps

Component Architecture

Learn how components work together

Solutions Overview

Explore pre-built solution packages

Build docs developers (and LLMs) love

Get started for freeTalk to us