Handling upload events

The uploader emits file selection, progress, success, and error events. Success means Chunkify has confirmed completion and created the Source.

UI states

The uploading attribute is present while preparing the session, transferring the file, and completing the upload.

• uploading means the attempt is in progress. Progress text displays a percentage, starting at 0% during session preparation and staying at 100% while completion runs.
• success means completion returned 204.
• error means the attempt could not finish. The Retry control returns to the initial state.

See customization for styling these attributes.

Events

File selection

file-selected, or onFileSelected, provides { file: File }. It fires after the file passes the component's size check, before the session provider runs.

Progress

upload-progress, or onUploadProgress, provides { progress: number }. It measures bytes transferred. Reaching 100% does not mean completion has succeeded.

Success

upload-success, or onUploadSuccess, provides { file: File }. Access the selected file through event.detail.file.

The event does not contain a Source ID because completion returns an empty 204 response. Your backend can obtain source_id from the upload.completed webhook or by reading the Upload with its project token. See webhooks.

const uploader = document.querySelector('chunkify-uploader');
uploader.addEventListener('upload-success', (event) => {
    console.log('Upload complete:', event.detail.file.name);
});

<ChunkifyUploader
    upload={createUpload}
    onUploadSuccess={(event) => {
        console.log('Upload complete:', event.detail.file.name);
    }}
>
    ...
</ChunkifyUploader>

Use the createUpload provider from setup.

Errors

upload-error, or onUploadError, provides:

{
    error: string;
    status: number;
}

error contains technical details for the integrating application. status is the HTTP status when available, zero for network failures or provider errors without a status, -1 for invalid configuration, or -2 for the component's file size limit.

A 403 completion response does not trigger automatic retries. It can indicate an account or storage configuration issue. Other temporary completion failures get a bounded automatic retry before an error event fires. See completion and retries.

Reset

upload-reset fires when the Retry control or a reset event resets the component. Reset cancels active browser requests and ignores pending provider results. It does not delete an Upload or remove a file from storage.

uploader.dispatchEvent(new Event('reset'));

Display errors to end users

Supply the error message in the component:

<chunkify-uploader-error>Upload failed. Please try again.</chunkify-uploader-error>
<chunkify-uploader-retry>Retry</chunkify-uploader-retry>

<ChunkifyUploaderError>Upload failed. Please try again.</ChunkifyUploaderError>
<ChunkifyUploaderRetry>Retry</ChunkifyUploaderRetry>

There is no built-in fallback for API, network, or completion errors. An empty error component has no message of its own. Supply text or update it in your upload-error handler.

The component writes its own message for configuration errors and files that exceed max-file-size, even if custom error content was supplied. Configuration errors include a missing provider or a missing, invalid, or already-used upload session.

Use the error event for application diagnostics or to choose your own user-facing message. Avoid displaying account or storage details directly to the end user.

<chunkify-uploader-error>Upload failed. Please try again.</chunkify-uploader-error>

You can also handle events through function properties:

uploader.onUploadError = (event) => {
    console.error(event.detail.status, event.detail.error);
};