# Core functionality of Mux Uploader

See the features that Mux Uploader includes with no extra configuration, such as chunked uploads, drag and drop, and progress UI. Use this guide to decide what to configure.

## [Mux Video integration](/content/docs/guides/uploader-web-core-functionality#mux-video-integration/index.html)

Mux Uploader is built for working with Mux's [Direct Uploads](/content/docs/guides/upload-files-directly/index.html) API and workflow. Add your upload URL as Mux Uploader's [`endpoint`](/content/docs/guides/mux-uploader#upload-a-video/index.html) to use it.

Mux Uploader uses [UpChunk](https://github.com/muxinc/upchunk) under the hood to handle large files by splitting them into small chunks before uploading them.

## [Controls and UI](/content/docs/guides/uploader-web-core-functionality#controls-and-ui/index.html)

Mux Uploader provides a feature-rich, dynamic UI that changes based on the current state of your media upload. These can be broken down into:

| State       | Attribute               | Description                                                                           |
| ----------- | ----------------------- | ------------------------------------------------------------------------------------- |
| Initial     | (none)                  | State before a media file has been selected for upload                               |
| In Progress | `upload-in-progress`    | State while media chunks are being uploaded                                          |
| Completed   | `upload-complete`       | State after the media has successfully finished uploading all chunks                 |
| Error       | `upload-error`          | State whenever an error occurs that results in a failure to fully upload the media    |

## [Initial State](/content/docs/guides/uploader-web-core-functionality#initial-state/index.html)

The initial state by default will show both a drag and drop region and a file select button to select your file for upload. By default, it looks like this:

## [In Progress State](/content/docs/guides/uploader-web-core-functionality#in-progress-state/index.html)

Under normal conditions, the in progress state will indicate the ongoing uploading progress as both a numeric percentage and a progress bar. It will look something like this:

### [Pausing](/content/docs/guides/uploader-web-core-functionality#pausing/index.html)

In addition, you can [opt into pausing](/content/docs/guides/uploader-web-customize-look-and-feel#enable-pausing/index.html), in which case the UI will look like one of these, depending on if you are unpaused, pausing (after the current chunk finishes uploading), or paused.

### [Offline](/content/docs/guides/uploader-web-core-functionality#offline/index.html)

Finally, if you unfortunately end up loosing internet connection while uploading is in progress, you'll see this:

## [Completed State](/content/docs/guides/uploader-web-core-functionality#completed-state/index.html)

Once uploading has completed, Mux Uploader will present the following status:

## [Error State](/content/docs/guides/uploader-web-core-functionality#error-state/index.html)

And in the unfortunate case where you encounter an error, by default you'll see the error message and a retry button:

If you want to explore different ways to customize the UI for these different states, check out our documentation on [customizing Mux Uploader's look and feel](/content/docs/guides/uploader-web-customize-look-and-feel/index.html).

## [Error handling](/content/docs/guides/uploader-web-core-functionality#error-handling/index.html)

Mux Uploader will monitor for unrecoverable errors and surface them via the UI, giving the user the opportunity to retry the upload. Mux Uploader monitors both HTTP-status based errors (e.g. 4xx, 5xx statuses) and file processing errors like exceeding maximum file size limits. See our [optional configuration options](/content/docs/guides/uploader-web-core-functionality#configure-upload-details/index.html) below for more ways to work around some of these errors.

In addition, before surfacing an HTTP-based error, Mux Uploader will automatically retry the request 5 times.

You may also listen for these errors via the `uploaderror` event, discussed in the section below.

## [Using events](/content/docs/guides/uploader-web-core-functionality#using-events/index.html)

All of Mux Uploader's core UI behaviors and functionality are driven by specific events. These fall into two categories:

1. user-driven update events (e.g. notifying Mux Uploader which file to upload or to retry uploading after an error)
2. state-driven informational events (e.g. notifying subcomponents or anyone else listening about the upload progress or that an error occurred)

For example, you can listen for the `progress` event to receive details on how far along your file upload is.

```

```

When the upload is complete, you'll see 100% on the progress bar and the `success` event will fire.

If an error occurs during the upload, an `uploaderror` event will fire.

### [Example HTML Usage](/content/docs/guides/uploader-web-core-functionality#example-html-usage/index.html)

```

```

### [Example React Usage](/content/docs/guides/uploader-web-core-functionality#example-react-usage/index.html)

```

```

## [Configure Upload Details](/content/docs/guides/uploader-web-core-functionality#configure-upload-details/index.html)

In addition to various UI customization and behaviors, Mux Uploader exposes the following attributes / properties for configuring details about the file upload itself:

| Attribute / Property                        | Description                                                                                                                                    |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `max-file-size` / `maxFileSize`           | The largest size, in kB, allowed for upload                                                                                                   |
| `chunk-size` / `chunkSize`                 | The size of each upload chunk, in kB. Useful for advanced optimization based on known network conditions or file details.                      |
| `dynamic-chunk-size` / `dynamicChunkSize` | A boolean that tells Mux Uploader to automatically adapt its chunk size larger or smaller based on network conditions.                          |
| `use-large-file-workaround` / `useLargeFileWorkaround` | A boolean that enables a less memory efficient way of loading and chunking files for environments that don't reliably handle [`ReadableStream` for large files](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams). This can occur on e.g. Safari browsers with files >= 4GB. **NOTE:** This fallback will only be used if and when attempts to use `ReadableStream` fails. |

## [Full API reference](/content/docs/guides/uploader-web-core-functionality#full-api-reference/index.html)

Any features or settings not mentioned above can be found in our [full API reference](https://github.com/muxinc/elements/blob/main/packages/mux-uploader/REFERENCE.md) covering all of the available events, attributes, properties, slots, CSS parts, and CSS variables available on Mux Uploader and all of its subcomponents.