File Uploader data output and event handling

All the File Uploader events are dispatched on the uc-upload-ctx-provider tag. You can catch them with the native addEventListener method, or use api.on() as a programmatic alternative that returns an unsubscribe function.

Attribute ctx-name is required for the uc-upload-ctx-provider tag, see Context for more details.

1
<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>
2
3
<script>
4
  const ctx = document.querySelector("uc-upload-ctx-provider");
5
  ctx.addEventListener("change", (e) => {
6
    console.log(e.detail);
7
  });
8
</script>

Quick start: log common events

If you want to quickly inspect what happens during the upload lifecycle, add listeners for the most common events and log event.detail to the console.

1
<uc-config
2
  ctx-name="my-uploader"
3
  pubkey="YOUR_PUBLIC_KEY"
4
  source-list="local, url, camera"
5
  use-cloud-image-editor="true">
6
</uc-config>
7
8
<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>
9
<uc-file-uploader-regular ctx-name="my-uploader"></uc-file-uploader-regular>
10
11
<script>
12
  const ctx = document.querySelector('uc-upload-ctx-provider');
13
14
  ctx.addEventListener('file-upload-start', (e) => {
15
    console.log('Start', e.detail);
16
  });
17
18
  ctx.addEventListener('file-upload-success', (e) => {
19
    console.log('Success', e.detail);
20
    console.log('UUID:', e.detail.uuid);
21
  });
22
23
  ctx.addEventListener('file-upload-failed', (e) => {
24
    console.log('Failed', e.detail);
25
  });
26
27
  ctx.addEventListener('change', (e) => {
28
    console.log('Change', e.detail);
29
  });
30
</script>

Note: Use console.log only for debugging. In production, connect these events to your analytics or telemetry system. Avoid logging PII.

Available events

In the event types below, we mention a few external types that aren’t described on this page:

• OutputFileEntry - see OutputFileEntry for more details.
• OutputCollectionState - see OutputCollectionState for more details.

file-added

Type: CustomEvent<OutputFileEntry>

Dispatched when a file is added to the upload list. The OutputFileEntry instance is in idle state. Could be suppressed if the silent option is set to true.

file-removed

Type: CustomEvent<OutputFileEntry>

Dispatched when a file is removed from the upload list. The OutputFileEntry instance is in removed state.

file-upload-start

Type: CustomEvent<OutputFileEntry>

Dispatched when a file upload starts. The OutputFileEntry instance is in uploading state. Could be suppressed if the silent option is set to true.

file-upload-progress

Type: CustomEvent<OutputFileEntry>

Dispatched when a file upload progress changes. The OutputFileEntry instance is in uploading state. Could be suppressed if the silent option is set to true.

file-upload-success

Type: CustomEvent<OutputFileEntry>

Dispatched when a file upload is successfully finished. The OutputFileEntry instance is in success state. Could be suppressed if the silent option is set to true.

file-upload-failed

Type: CustomEvent<OutputFileEntry>

Dispatched when a file upload fails. The OutputFileEntry instance is in failed state

file-url-changed

Type: CustomEvent<OutputFileEntry>

Dispatched when a file CDN URL is changed. This occurs when a file is uploaded and the CDN URL becomes available, or when a file is edited with the Image editor that changes the CDN URL.

modal-open

Type: CustomEvent<{modalId: "start-from" | "camera" | "upload-list" | "url" | "confirmation" | "cloud-image-edit" | "external" }>

modalId – a field that lets you know which modal used.

Available in: regular and minimal modes

Dispatched when the modal is opened.

modal-close

Type: CustomEvent<{modalId: "start-from" | "camera" | "upload-list" | "url" | "confirmation" | "cloud-image-edit" | "external"; hasActiveModals: boolean }>

modalId – a field that lets you know which modal used. hasActiveModals – a field that lets you know if any modals are active at the moment.

Available in: regular and minimal modes

Dispatched when the modal is closed.

done-click

Type: CustomEvent<OutputCollectionState>

Available in: regular and inline modes

Dispatched when the Done button is clicked.

upload-click

Type: CustomEvent<void>

Available in: regular and inline modes

Dispatched when the Upload button is clicked.

activity-change

Type: CustomEvent<{ activity: "start-from" | "camera" | "upload-list" | "url" | "confirmation" | "cloud-image-edit" | "external" | null }>

Dispatched when the activity changes.

common-upload-start

Type: CustomEvent<OutputCollectionState>

Dispatched when an upload process starts. The OutputCollectionState instance is in uploading status.

It could be triggered in the following cases:

• When the confirmUploads option is set to true and there are ready-to-upload files in the list.
• When the upload process is started using the API.
• When the user clicks the Upload button.

common-upload-progress

Type: CustomEvent<OutputCollectionState>

Dispatched when an upload process progress changes. The OutputCollectionState instance is in uploading status.

The progress is calculated for those files that were ready to upload at the moment when the upload process was started. That means, for example, if there were 3 uploaded files in the list, and the user added 2 more files, the progress will be calculated for those 2 new files only.

common-upload-success

Type: CustomEvent<OutputCollectionState>

Dispatched when an upload process is successfully finished. The OutputCollectionState instance is in success status.

The upload process is considered as successfully finished when all the files in the list are successfully uploaded. If there are any uploading, failed or idle files - the upload process isn’t considered as successfully finished.

common-upload-failed

Type: CustomEvent<OutputCollectionState>

Dispatched when an upload process fails. The OutputCollectionState instance is in failed status.

The upload process is considered as failed when any of the file in the list is in a failed status.

change

Type: CustomEvent<OutputCollectionState>

Dispatched when the upload list changes. Any change in the upload list itself or in the files state will trigger this event.

group-created

Type: CustomEvent<OutputCollectionState>

Dispatched when a group is created. Group will be created when the groupOutput option is set to true and when the upload process is considered as successfully finished.