File Uploader API

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.

1
<link
2
  rel="stylesheet"
3
  href="https://cdn.jsdelivr.net/npm/@uploadcare/file-uploader@v1/web/uc-file-uploader-regular.min.css"
4
/>
5
6
<uc-config pubkey="YOUR_PUBLIC_KEY" ctx-name="my-uploader"></uc-config>
7
8
<uc-upload-ctx-provider
9
  id="uploaderctx"
10
  ctx-name="my-uploader"
11
></uc-upload-ctx-provider>
12
13
<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:

1
// Get reference to the DOM element
2
const uploaderCtx = document.querySelector('#uploaderctx')
3
4
// Get reference to the API instance
5
const api = uploaderCtx.getAPI()
6
7
// Use the API methods
8
const collectionState = api.getOutputCollectionState()

Get file entry by Internal ID

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.

1
type SourceType = "facebook" | "dropbox" | "gdrive" | "gphotos" | "box" | "onedrive" | "local" | "drop-area" | "camera" | "external" | "js-api" | "url" | "draw";
2
3
type OutputFileEntry = {
4
  internalId: string;
5
6
  status:
7
    | 'idle'
8
    | 'uploading'
9
    | 'success'
10
    | 'failed'
11
    | 'removed';
12
13
  // those flags are based on the status property
14
  isUploading: boolean;
15
  isSuccess: boolean;
16
  isFailed: boolean;
17
  isRemoved: boolean;
18
19
  name: string;
20
  size: number;
21
  isImage: boolean;
22
  mimeType: string;
23
  metadata: Record<string, string> | null;
24
25
  file: File | Blob | null;
26
  externalUrl: string | null;
27
  uploadProgress: number;
28
  fullPath: string | null;
29
30
  fileInfo: UploadcareFile | null;
31
  uuid: string | null;
32
  cdnUrl: string | null;
33
  cdnUrlModifiers: string | null;
34
  source: SourceType | null;
35
36
  errors: {
37
    type:
38
      | 'NOT_AN_IMAGE'
39
      | 'FORBIDDEN_FILE_TYPE'
40
      | 'FILE_SIZE_EXCEEDED'
41
      | 'UPLOAD_ERROR'
42
      | 'NETWORK_ERROR'
43
      | 'UNKNOWN_ERROR';
44
    message: string;
45
    // additional payload depending on the error type
46
    ...payload
47
  }[];
48
}

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.

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

Get upload 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.

1
type OutputCollectionState = {
2
  status: 'idle' | 'uploading' | 'success' | 'failed';
3
  group: UploadcareGroup | null;
4
5
  isFailed: boolean;
6
  isUploading: boolean;
7
  isSuccess: boolean;
8
9
  totalCount: number;
10
  successCount: number;
11
  failedCount: number;
12
  uploadingCount: number;
13
  progress: number;
14
15
  allEntries: OutputFileEntry[];
16
  successEntries: OutputFileEntry[];
17
  failedEntries: OutputFileEntry[];
18
  uploadingEntries: OutputFileEntry[];
19
  idleEntries: OutputFileEntry[];
20
21
  errors: {
22
    type:
23
      | 'SOME_FILES_HAS_ERRORS'
24
      | 'TOO_MANY_FILES'
25
      | 'TOO_FEW_FILES';
26
    message: string;
27
    // additional payload depending on the error type
28
    ...payload
29
  }[];
30
}

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.

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:

1
const plainOutputCollectionState = {
2
  ...uploaderCtx.getOutputCollectionState()
3
}

Upload all

uploadAll() => void

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

Add file from File or Blob

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: 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: 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 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 used (regular, inline, or minimal) and is particularly useful for the regular option when you want to close the dialog programmatically.

Set current activity

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

1
type ActivityType =
2
  | 'start-from'
3
  | 'camera'
4
  | 'upload-list'
5
  | 'url'
6
  | 'cloud-image-edit'
7
  | 'external'
8
  | 'details'
9
10
type ExternalSourceType =
11
  | 'facebook'
12
  | 'dropbox'
13
  | 'gdrive'
14
  | 'gphotos'
15
  | 'box'
16
  | 'onedrive'
17
18
type ActivityParams<T extends ActivityType> = T extends 'external'
19
  ? {
20
      externalSourceType: ExternalSourceType
21
    }
22
  : {}

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.

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:

1
api.setCurrentActivity('external', {
2
  externalSourceType: 'gdrive'
3
})
4
5
api.setModalState(true)

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.

1
api.historyBack()

Set modal dialog 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:

1
api.setCurrentActivity('start-from')
2
api.setModalState(true)

Subscribe to uploader events

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.

1
import { EventType } from '@uploadcare/file-uploader';
2
3
const unsubscribe = api.on(EventType.FILE_UPLOAD_SUCCESS, (fileEntry) => {
4
  console.log('Uploaded:', fileEntry.cdnUrl);
5
});
6
7
// Stop listening
8
unsubscribe();

For the full list of available events and their payloads, see Events.

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

1
import { EventType } from '@uploadcare/file-uploader';
2
3
setup({ uploaderApi }) {
4
  const unsubscribe = uploaderApi.on(EventType.FILE_UPLOAD_SUCCESS, (fileEntry) => {
5
    if (fileEntry.isImage) {
6
      console.log('Image uploaded:', fileEntry.cdnUrl);
7
    }
8
  });
9
10
  return () => unsubscribe();
11
}

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 section. Plugins can register additional translation keys via registerL10n.

Configuration

get cfg() => ConfigType

This method returns the current Uploader configuration. It’s useful for the custom validation described in the Validators section.

Usage example:

1
const publicKey = api.cfg.pubkey