Events

The uploader emits browser events for file selection, progress, completion, errors, and resets. Listen with addEventListener, a function property, or the React callback prop.

Upload success means Chunkify confirmed completion and created the Source. It does not mean an automatically created video asset is ready to stream. Use webhooks for server-side processing updates.

UI states

See Styles for customizing these states.

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. Retrying the same attempt does not fire another file-selection event.

Progress

upload-progress, or onUploadProgress, provides { progress: number }. It measures bytes transferred across the whole file, including completed multipart parts.

Progress can decrease when a failed request restarts. Reaching 100% does not mean completion succeeded. The component remains uploading while it confirms completion.

Success

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

The event has no Source or video asset ID because completion returns an empty 204 response. Your backend can read those IDs from the Upload or the upload.completed webhook.

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);
    }}
>
    {/* Your uploader components */}
</ChunkifyUploader>

Use the provider and component imports from Get started.

Errors

upload-error, or onUploadError, provides:

{
    error: string;
    status: number;
}

The event fires after automatic request retries are exhausted or a non-retryable error occurs. Check retryable to determine whether the same attempt can continue. See retry behavior.

Reset

upload-reset fires when uploader.reset() or a reset event clears the attempt. Reset aborts active browser requests, discards the file and session, and returns the component to file selection.

Removing the component also resets it. Reset does not delete the Upload or abort incomplete multipart data in storage. Your storage's lifecycle rules should remove abandoned multipart uploads.

Retry or start over

The Retry child component continues a recoverable failure. You can also call retry() directly:

const uploader = document.querySelector('chunkify-uploader');

// Continue the failed step with the retained file and session.
uploader.retry();

Successful parts are retained. If transfer finished, Retry repeats only completion. If the session provider failed before supplying a valid session, Retry calls it again.

To discard the attempt and select a file again, reset explicitly:

uploader.reset();

// Equivalent when dispatching from a custom control.
uploader.dispatchEvent(new Event('reset'));

The next selection needs a fresh session. An async provider creates one automatically. An existing session object must be replaced before the next attempt.

Display errors

An empty error component displays the uploader's fallback message for transfer and completion errors:

<chunkify-uploader-error></chunkify-uploader-error>
<chunkify-uploader-retry>Retry</chunkify-uploader-retry>

Supply custom content for a message you control. The same behavior applies to React children:

<ChunkifyUploaderError>Upload failed. Retry or start over.</ChunkifyUploaderError>
<ChunkifyUploaderRetry>Retry</ChunkifyUploaderRetry>

File-size and session-configuration errors replace custom content with their validation message. For other errors, your content takes priority over the fallback message.

Use upload-error to collect diagnostics or choose a message for your interface. Keep technical account or storage details out of end-user messages.

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