> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# File Uploader API

> Manage the File Uploader via the API. Learn how to set metadata for uploaded files and use the context provider.

For convenience, we provide the `<uc-upload-ctx-provider>` tag, which offers
additional uploader management methods. Simply place the context provider on the
page and wire it to the uploader via the `ctx-name` attribute.

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css"
/>

<uc-config pubkey="YOUR_PUBLIC_KEY" ctx-name="my-uploader"></uc-config>

<uc-upload-ctx-provider
  id="uploaderctx"
  ctx-name="my-uploader"
></uc-upload-ctx-provider>

<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
```

To access the `UploaderPublicApi` instance and utilize its methods, simply retrieve it
as follows:

```js
// Get reference to the DOM element
const uploaderCtx = document.querySelector('#uploaderctx')

// Get reference to the API instance
const api = uploaderCtx.getAPI()

// Use the API methods
const collectionState = api.getOutputCollectionState()
```

## Get file entry by Internal ID \[#output-file-entry]

`getOutputItem(internalId: string) => OutputFileEntry`

Returns a file entry by its internal ID. Internal ID is a unique identifier of a
file entry within the File Uploader instance. It is generated automatically and
can be accessed via the `internalId` property of the `OutputFileEntry` object.
It's not related to the UUID of the uploaded file.

Here is the interface of the returned object. Since it's originally described in
TypeScript with generics that could be hard to understand, we've simplified it
for the sake of clarity.

```ts
type SourceType = "facebook" | "dropbox" | "gdrive" | "gphotos" | "box" | "onedrive" | "local" | "drop-area" | "camera" | "external" | "js-api" | "url" | "draw";

type OutputFileEntry = {
  internalId: string;

  status:
    | 'idle'
    | 'uploading'
    | 'success'
    | 'failed'
    | 'removed';

  // those flags are based on the status property
  isUploading: boolean;
  isSuccess: boolean;
  isFailed: boolean;
  isRemoved: boolean;

  name: string;
  size: number;
  isImage: boolean;
  mimeType: string;
  metadata: Record<string, string> | null;

  file: File | Blob | null;
  externalUrl: string | null;
  uploadProgress: number;
  fullPath: string | null;

  fileInfo: UploadcareFile | null;
  uuid: string | null;
  cdnUrl: string | null;
  cdnUrlModifiers: string | null;
  source: SourceType | null;

  errors: {
    type:
      | 'NOT_AN_IMAGE'
      | 'FORBIDDEN_FILE_TYPE'
      | 'FILE_SIZE_EXCEEDED'
      | 'UPLOAD_ERROR'
      | 'NETWORK_ERROR'
      | 'UNKNOWN_ERROR';
    message: string;
    // additional payload depending on the error type
    ...payload
  }[];
}
```

Status is one of the following:

* `idle`: the file is in the upload list, but it's not started uploading yet.
* `uploading`: the file is currently uploading.
* `failed`: the file failed to upload.
* `success`: the file was successfully uploaded.
* `removed`: the file was removed from the upload list.

The `UploadcareFile` type is described in the
[@uploadcare/upload-client API docs](https://uploadcare.github.io/uploadcare-js-api-clients/upload-client/classes/UploadcareFile.html).

The `SourceType` type is a list of sources from which the file can be uploaded.

## Get upload collection state \[#output-collection-state]

`getOutputCollectionState() => OutputCollectionState`

Returns the entire state of the upload list.

Here is the interface of the returned object. Since it's originally described in
TypeScript with generics that could be hard to understand, we've simplified it
for the sake of clarity.

```ts
type OutputCollectionState = {
  status: 'idle' | 'uploading' | 'success' | 'failed';
  group: UploadcareGroup | null;

  isFailed: boolean;
  isUploading: boolean;
  isSuccess: boolean;

  totalCount: number;
  successCount: number;
  failedCount: number;
  uploadingCount: number;
  progress: number;

  allEntries: OutputFileEntry[];
  successEntries: OutputFileEntry[];
  failedEntries: OutputFileEntry[];
  uploadingEntries: OutputFileEntry[];
  idleEntries: OutputFileEntry[];

  errors: {
    type:
      | 'SOME_FILES_HAS_ERRORS'
      | 'TOO_MANY_FILES'
      | 'TOO_FEW_FILES';
    message: string;
    // additional payload depending on the error type
    ...payload
  }[];
}
```

Status is one of the following:

* `idle`: there are no files in the upload list, or some files have the `idle`
  status and none of them have the `uploading` or `failed` status. In case when
  the `confirm-upload` option is enabled and there are `success` files along
  with the `idle` ones: the collection status is `idle`.
* `uploading`: some files have the `uploading` status and none of them have the
  `failed` status.
* `failed`: some files have the `failed` status.
* `success`: all files have the `success` status.

The `UploadcareGroup` type is described in the
[@uploadcare/upload-client API docs](https://uploadcare.github.io/uploadcare-js-api-clients/upload-client/classes/UploadcareGroup.html).

Note that the returned object isn't a plain object. It has special
lazy-evaluated properties that are computed on demand. This is done to avoid
unnecessary computations and memory allocations. Those properties are expected
to be accessed synchronously, so if you need to access them asynchronously, you
should copy them to a plain object first:

```ts
const plainOutputCollectionState = {
  ...uploaderCtx.getOutputCollectionState()
}
```

## Upload all

`uploadAll() => void`

This method uploads all files that are currently in the upload list.

## Add file from File or Blob \[#add-file-from-object]

`addFileFromObject(file: File | Blob, options?: { silent?: boolean; fileName?: string; }) => OutputFileEntry`

Add a file to the upload list from a `File` object. The `options` parameter is
optional:

* `silent`: if `true`, events `file-added`, `file-upload-start`,
  `file-upload-progress`, `file-upload-success` won't be triggered.
* `fileName`: the name of the file to be displayed in the upload list.

## Add file from UUID

`addFileFromUuid(uuid: string, options?: { silent?: boolean; fileName?: string; }) => OutputFileEntry`

Add a file to the upload list from a UUID. The `options` parameter is optional:

* `silent`: if `true`, events `file-added`, `file-upload-start`,
  `file-upload-progress`, `file-upload-success` won't be triggered.
* `fileName`: the name of the file to be displayed in the upload list.

## Add file from URL

`addFileFromUrl(url: string, options?: { silent?: boolean; fileName?: string; }) => OutputFileEntry`

Add a file to the upload list from a URL. The `options` parameter is optional:

* `silent`: if `true`, events `file-added`, `file-upload-start`,
  `file-upload-progress`, `file-upload-success` won't be triggered.
* `fileName`: the name of the file to be displayed in the upload list.

## Add a file from Uploadcare CDN URL

`addFileFromCdnUrl(cdnUrl: string, options?: { silent?: boolean; fileName?: string; }) => OutputFileEntry`

Add a file to the upload list from an Uploadcare CDN URL. It's useful when you
wish to add a previously uploaded file to Uploadcare with the processing
operations applied.

The `options` parameter is optional:

* `silent`: if `true`, events `file-added`, `file-upload-start`,
  `file-upload-progress`, `file-upload-success` won't be triggered.
* `fileName`: the file name to be displayed in the upload list.

## Remove file by Internal ID

`removeFileByInternalId(internalId: string) => void`

Remove a file from the upload list by its internal ID.

> **Note**
>
> **Note:** This method doesn't remove the file from the server. It only removes
> it from the upload list.

## Remove all files

`removeAllFiles() => void`

Remove all files from the upload list.

> **Note**
>
> **Note:** This method doesn't remove the files from the server. It only removes
> them from the upload list.

## Init uploader flow

`initFlow() => void`

This method initiates the uploader flow. Its behavior varies depending on the
[solution](/docs/file-uploader/options/) used (regular, inline, or minimal), and it is
particularly useful for the regular option when you want to open the dialog
programmatically.

## Done uploader flow

`doneFlow() => void`

This method terminates the uploader flow. Its behavior depends on the
[solution](/docs/file-uploader/options/) used (regular, inline, or minimal) and is
particularly useful for the regular option when you want to close the dialog
programmatically.

## Set current activity \[#set-current-activity]

`setCurrentActivity(activityType: ActivityType, params: ActivityParams<typeof activityType> = {}) => void`

```ts
type ActivityType =
  | 'start-from'
  | 'camera'
  | 'upload-list'
  | 'url'
  | 'cloud-image-edit'
  | 'external'
  | 'details'

type ExternalSourceType =
  | 'facebook'
  | 'dropbox'
  | 'gdrive'
  | 'gphotos'
  | 'box'
  | 'onedrive'

type ActivityParams<T extends ActivityType> = T extends 'external'
  ? {
      externalSourceType: ExternalSourceType
    }
  : {}
```

This method sets the current activity of the Uploader. It's useful when you want
to programmatically switch between the Uploader's activities. For example, you
can switch to the camera activity to start capturing images or to the URL
activity to paste a URL. Custom activities can be registered via the [Plugin API](/docs/file-uploader/plugins/#registeractivity).

Note: Activity could reset itself if it can't be set for some reason. For
example, when there are no files in the upload list, and the `confirmUpload`
option is disabled, the `upload-list` activity won't be set.

Also, this method won't open the modal dialog if it's closed. To open the modal
dialog after the current activity is set, use the `setModalState` method.

Second argument `params` is optional and depends on the activity type. For now,
the only activity that requires additional parameters is the `external`
activity. It requires the `externalSourceType` parameter that should be one of
the `ExternalSourceType` values. This parameter is used to set the source of the
external activity: Dropbox, Google Drive, etc.

Usage example:

```ts
api.setCurrentActivity('external', {
  externalSourceType: 'gdrive'
})

api.setModalState(true)
```

## History back \[#history-back]

`historyBack() => void`

Navigates back to the previous activity in the navigation history stack, the same way the built-in Back button does. If there is no previous activity, the modal is closed.

This is the recommended way to implement a Back button in a custom activity. It is also available as `uploaderApi.historyBack()` inside plugin code.

```ts
api.historyBack()
```

## Set modal dialog state \[#set-modal-state]

`setModalState(opened: boolean) => void`

This method opens or closes the modal dialog of the Uploader. It's particularly
useful for the regular mode when you want to open the dialog programmatically
with the needed activity.

The difference between this method and the `initFlow` or `doneFlow` methods is
that this method doesn't include any additional logic. It just opens or closes
the modal dialog. `initFlow` and `doneFlow` methods include additional logic
that could open the system file picker and chooses the right activity to set
based on the current state of the Uploader: enabled sources, files count, etc.

Usage example:

```ts
api.setCurrentActivity('start-from')
api.setModalState(true)
```

## Subscribe to uploader events \[#on]

`on(type: EventType, handler: (payload) => void) => () => void`

Subscribes to a built-in uploader event. Returns an unsubscribe function. Call it to stop listening, or return it from a plugin's `setup` to have it cleaned up automatically when the plugin is unregistered.

```ts
import { EventType } from '@uploadcare/file-uploader';

const unsubscribe = api.on(EventType.FILE_UPLOAD_SUCCESS, (fileEntry) => {
  console.log('Uploaded:', fileEntry.cdnUrl);
});

// Stop listening
unsubscribe();
```

For the full list of available events and their payloads, see [Events](/docs/file-uploader/events/).

Inside a plugin `setup`, return the unsubscribe function to have it called automatically when the plugin is removed:

```typescript
import { EventType } from '@uploadcare/file-uploader';

setup({ uploaderApi }) {
  const unsubscribe = uploaderApi.on(EventType.FILE_UPLOAD_SUCCESS, (fileEntry) => {
    if (fileEntry.isImage) {
      console.log('Image uploaded:', fileEntry.cdnUrl);
    }
  });

  return () => unsubscribe();
}
```

---

## Localization

`l10n(key: string, params?: Record<string, string>) => string`

This method allows you to get a localized string by its key. It's necessary for
the custom validation error messages described in the
[Validators](/docs/file-uploader/validators/) section. Plugins can register additional translation keys via [`registerL10n`](/docs/file-uploader/plugins/#registerl10n).

## Configuration

`get cfg() => ConfigType`

This method returns the current Uploader configuration. It's useful for
the custom validation described in the [Validators](/docs/file-uploader/validators/)
section.

Usage example:

```ts
const publicKey = api.cfg.pubkey
```