@wordpress/upload-media

This module is a media upload handler with a queue-like system that is implemented using a custom @wordpress/data store.

Such a system is useful for additional client-side processing of media files (e.g. image compression) before uploading them to a server.

It is typically used by @wordpress/block-editor but can also be leveraged outside of it.

Installation

Install the module

npm install @wordpress/upload-media --save

Usage

This is a basic example of how one can interact with the upload data store:

import { store as uploadStore } from '@wordpress/upload-media';
import { dispatch } from '@wordpress/data';

dispatch( uploadStore ).updateSettings( /* ... */ );
dispatch( uploadStore ).addItems( [
    /* ... */
] );

Refer to the API reference below or the TypeScript types for further help.

API Reference

Actions

The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core/upload-media' ):

addItems

Adds a new item to the upload queue.

Parameters

• $0 AddItemsArgs:
• $0.files AddItemsArgs[ 'files' ]: Files
• $0.onChange [AddItemsArgs[ 'onChange' ]]: Function called each time a file or a temporary representation of the file is available.
• $0.onSuccess [AddItemsArgs[ 'onSuccess' ]]: Function called after the file is uploaded.
• $0.onBatchSuccess [AddItemsArgs[ 'onBatchSuccess' ]]: Function called after a batch of files is uploaded.
• $0.onError [AddItemsArgs[ 'onError' ]]: Function called when an error happens.
• $0.additionalData [AddItemsArgs[ 'additionalData' ]]: Additional data to include in the request.
• $0.allowedTypes [AddItemsArgs[ 'allowedTypes' ]]: Array with the types of media that can be uploaded, if unset all types are allowed.

cancelItem

Cancels an item in the queue based on an error.

If the error is retryable and the item hasn’t exceeded the maximum retry attempts, it will be scheduled for automatic retry instead of being cancelled.

Parameters

• id QueueItemId: Item ID.
• error Error: Error instance.
• silent Whether to cancel the item silently, without invoking its onError callback.

executeRetry

Executes a scheduled retry for an item.

This is called by the timer set in scheduleRetry. It verifies the item is still in PendingRetry status before proceeding with the retry.

Parameters

• id QueueItemId: Item ID.

retryItem

Retries a failed item in the queue.

Parameters

• id QueueItemId: Item ID.

scheduleRetry

Schedules an automatic retry for a failed item.

Uses exponential backoff with jitter to determine the retry delay. The item will be placed in PendingRetry status and automatically retried after the calculated delay.

Parameters

• id QueueItemId: Item ID.
• error Error: The error that caused the failure.

Selectors

The following selectors are available on the object returned by wp.data.select( 'core/upload-media' ):

getItems

Returns all items currently being uploaded.

Parameters

• state State: Upload state.

Returns

• QueueItem[]: Queue items.

getSettings

Returns the media upload settings.

Parameters

• state State: Upload state.

Returns

• Settings: Settings

isUploading

Determines whether any upload is currently in progress.

Parameters

• state State: Upload state.

Returns

• boolean: Whether any upload is currently in progress.

isUploadingById

Determines whether an upload is currently in progress given an attachment ID.

Parameters

• state State: Upload state.
• attachmentId number: Attachment ID.

Returns

• boolean: Whether upload is currently in progress for the given attachment.

isUploadingByUrl

Determines whether an upload is currently in progress given an attachment URL.

Parameters

• state State: Upload state.
• url string: Attachment URL.

Returns

• boolean: Whether upload is currently in progress for the given attachment.