@wordpress/upload-media/README.md

Core media upload logic.

# Upload Media

<div class="callout callout-alert">
This package is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
</div>

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

```bash
npm install @wordpress/upload-media --save
```

## Usage

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

```js
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' )`:

<!-- START TOKEN(Autogenerated actions|src/store/actions.ts) -->

#### 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.

<!-- END TOKEN(Autogenerated actions|src/store/actions.ts) -->

### Selectors

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

<!-- START TOKEN(Autogenerated selectors|src/store/selectors.ts) -->

#### 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.

<!-- END TOKEN(Autogenerated selectors|src/store/selectors.ts) -->