> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.

# File Uploader data output and event handling

> Learn how to handle data output and events in the File Uploader.

> **Warning**
>
> **Warning:** In the v0.32.0 release, global events are removed and all the existing events
> are updated. See the [migration guide](/docs/file-uploader/migration-to-0.32.0/).

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()`](/docs/file-uploader/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](/docs/file-uploader/configuration/#context-ctx-name) for more details.

```html
<uc-upload-ctx-provider ctx-name="my-uploader"></uc-upload-ctx-provider>

<script>
  const ctx = document.querySelector("uc-upload-ctx-provider");
  ctx.addEventListener("change", (e) => {
    console.log(e.detail);
  });
</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.

```html
<uc-config
  ctx-name="my-uploader"
  pubkey="YOUR_PUBLIC_KEY"
  source-list="local, url, camera"
  use-cloud-image-editor="true">
</uc-config>

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

<script>
  const ctx = document.querySelector('uc-upload-ctx-provider');

  ctx.addEventListener('file-upload-start', (e) => {
    console.log('Start', e.detail);
  });

  ctx.addEventListener('file-upload-success', (e) => {
    console.log('Success', e.detail);
    console.log('UUID:', e.detail.uuid);
  });

  ctx.addEventListener('file-upload-failed', (e) => {
    console.log('Failed', e.detail);
  });

  ctx.addEventListener('change', (e) => {
    console.log('Change', e.detail);
  });
</script>
```

> **Warning**
>
> **Warning:** 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](/docs/file-uploader/api/#output-file-entry) for more details.
* `OutputCollectionState`: see
  [OutputCollectionState](/docs/file-uploader/api/#output-collection-state) 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](/docs/file-uploader/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](/docs/file-uploader/options/#group-output) is set to
`true` and when the upload process is considered as successfully finished.