Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@wordpress/upload-media) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

(Experimental) 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.

Parameters

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

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.