Skip to main content

Events

The Uploader will trigger for batch and batch-item lifecycle events.

Registering to handle events can be done using the uploader's on() and once() methods. Unregistering can be done using off() or by calling the return value (function) of both on() and once().

info

See UPLOADER_EVENTS in constants

const batchAddHandler = (batch) => {};

const unregister = uploader.on(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);

unregister(); //is equivalent to the line below
uploader.off(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);

BATCH_ADD​

Parameters: (batch: Batch, options: CreateOptions)

Triggered when a new batch is added.

info

This event is cancellable

BATCH_START​

Parameters: (batch: Batch, options: CreateOptions)

Triggered when batch items start uploading

The handler can change data inside the items and in the options by returning different data than received.

info

This event is cancellable

BATCH_PROGRESS​

Parameters: (batch: Batch, options: CreateOptions)

Triggered every time progress data is received from the upload request(s)

BATCH_FINISH​

  • Parameters: (batch, options: CreateOptions)

Triggered when batch items finished uploading

BATCH_CANCEL​

Parameters: (batch: Batch, options: CreateOptions)

Triggered in case batch was cancelled from BATCH_START event handler

BATCH_ABORT​

Parameters: (batch: Batch, options: CreateOptions)

Triggered in case the batch was aborted

BATCH_ERROR​

Parameters: (batch: Batch, options: CreateOptions)

Triggered in case the batch was failed with an error. These errors will most likely occur due to invalid event handling. For instance, by a handler (ex: BATCH_START) throwing an error.

BATCH_FINALIZE​

Parameters: (batch: Batch, options: CreateOptions)

Triggered when all batch items have finished uploading or in case the batch was cancelled(abort) or had an error

note

This event can be relied on to be called regardless of how the batch finished

ITEM_START​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered when item starts uploading (just before) For grouped uploads (multiple files in same xhr request) ITEM_START is triggered for each item separately

info

This event is cancellable

ITEM_FINISH​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered when item finished uploading successfully

note

The server response can be accessed through the item's uploadResponse property and status code through uploadStatus

ITEM_PROGRESS​

Parameters: (item: BatchItem)

Triggered every time progress data is received for this file upload

note

progress info is accessed through the item's "completed" (percentage) and "loaded" (bytes) properties.

ITEM_CANCEL​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered in case item was cancelled programmatically

ITEM_ERROR​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered in case item upload failed

note

The server response can be accessed through the item's uploadResponse property.

ITEM_ABORT​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered in case abort was called

ITEM_FINALIZE​

Parameters: (item: BatchItem, options: CreateOptions)

Triggered for item when uploading is done due to: finished, error, cancel or abort Use this event if you want to handle the state of the item being done for any reason.

note

This event can be relied on to be called regardless of how the item finished

REQUEST_PRE_SEND​

Parameters: (items: BatchItem[], options: CreateOptions)

Triggered before a group of items is going to be uploaded Group will contain a single item unless "grouped" option is set to true.

Handler receives the item(s) in the group and the upload options that were used. The handler can change data inside the items and in the options by returning different data than received. See this guide for more details.

info

This event is cancellable

ALL_ABORT​

No parameters: ()

Triggered when abort is called without an item id (abort all)

Cancellable Events​

These are events that allow the client to cancel their respective upload object (batch or batch-item) To cancel the upload, the handler must return (boolean) false.

uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
    let result;
    
    if (item.file.name.endsWith(".xml")) {
        result = false; //only false will cause a cancel.
    }

    return result;
});

Chunk Events​

CHUNK_START​

Parameters: (data: ChunkStartEventData)

Triggered when a chunk begins uploading as part of a chunked upload

CHUNK_FINISH​

Parameters: (data: ChunkFinishEventData)

Triggered when a chunk finishes uploading as part of a chunked upload

RETRY_EVENT​

Triggered when files are re-added to the queue for retry.

Parameters: ({ uploads: BatchItem[], options?: UploadOptions })

note

uploads is an array of batch items.

note

options are the (optional) upload options that are passed to the retry call

Tus Events​

RESUME_START​

Parameters: (data: ResumeStartEventData)

Triggered before the (HEAD) request is issued on behalf of a potentially resumeable upload.

info

This event is cancellable

Cancelling the request will not abort the entire upload, but rather cancel the fetching of resume info.