File Uploader API

For convenience, we provide the <lr-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.

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

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

<lr-file-uploader-inline
  css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@{{__BLOCKS_VERSION__}}/web/lr-file-uploader-inline.min.css"
  ctx-name="my-uploader"
></lr-file-uploader-inline>

To access the context provider element and utilize its methods, simply retrieve it as follows:

const uploaderCtx = document.querySelector('#uploaderctx')
const collectionState = uploaderCtx.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.

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: null | null;
  cdnUrl: null | null;
  cdnUrlModifiers: string | 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.

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.

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

  isFailed: false;
  isUploading: false;
  isSuccess: false;

  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.

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:

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

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.