Pickers

The SDK includes built-in picker modals for bucket, folder, and file selection. These appear automatically during upload() and download() calls when the target is ambiguous or when the user needs to choose a destination.

Pickers can be disabled entirely by setting ui: { disabled: true } in the Upl constructor.

When pickers appear

During upload

Bucket picker — if neither bucketId nor bucketHint resolves to a single bucket
Folder picker — if pickerConfig.enabled is true (default when UI is enabled), allowing the user to choose a destination folder, edit the filename, or select an existing file to overwrite

During download

Bucket picker — if the bucket can't be resolved
File picker — if filters match multiple uploads and nonInteractive is not set

Upload picker configuration

await upl.upload({
  filename: 'report.pdf',
  bucketHint: 'my-bucket',
  pickerConfig: {
    enabled: true,                // Show folder picker (default: true)
    allowOverwrite: true,         // Allow selecting an existing file to replace
    overwriteTarget: 'upl_123',  // Pre-select a file to overwrite
    allowFilenameEdit: true,      // Allow editing filename (default: true)
    allowSlugEdit: false,         // Allow editing URL slug (default: false)
    selectionFilter: {
      extensions: ['pdf', 'doc', 'docx'],
    },
  },
}, data);

Option	Type	Default	Description
`enabled`	`boolean`	`true`	Show folder picker before upload
`allowOverwrite`	`boolean`	`false`	Allow replacing existing files
`overwriteTarget`	`string`	—	Pre-select upload ID to overwrite
`allowFilenameEdit`	`boolean`	`true`	Allow editing filename in picker
`allowSlugEdit`	`boolean`	`false`	Allow editing URL slug in picker
`selectionFilter`	`UploadSelectionFilter`	—	Filter visible files by type

Download picker configuration

await upl.download({
  bucketHint: 'my-bucket',
  path: '/images',
  pickerConfig: {
    preselectUpload: 'upl_456',   // Pre-select an upload in the picker
    selectionFilter: {
      extensions: ['jpg', 'png', 'gif', 'webp'],
    },
  },
});

Option	Type	Default	Description
`preselectUpload`	`string`	—	Pre-select an upload ID
`selectionFilter`	`UploadSelectionFilter`	—	Filter visible files

Selection filters

Selection filters control which files are visible and selectable in the picker:

interface UploadSelectionFilter {
  extensions?: string[];   // File extensions (e.g. ['jpg', 'png'])
  types?: UploadType[];    // Upload types (e.g. [UploadType.IMAGE])
}

Extensions are normalised (lowercase, dot-prefix removed) and matched against the file's slug, filename, or path.

Picker features

The built-in pickers include:

Breadcrumb navigation with folder shortcuts
Real-time search with debouncing
Integration folder handling for custom folder types
Keyboard navigation support
Dark theme UI that overlays your application

Skipping pickers

To bypass pickers entirely:

Upload: set pickerConfig.enabled: false and provide explicit bucketId + path
Download: set nonInteractive: true and provide explicit bucketId + uploadId
Global: set ui: { disabled: true } on the Upl constructor — all ambiguous cases will throw instead of opening a picker

Pickers

On this page