Title: @wordpress/upload-media
Published: January 7, 2025
Last modified: October 9, 2026

---

# @wordpress/upload-media

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#installation)
 * [Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#usage)
 * [API Reference](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#api-reference)
    - [Actions](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#actions)
    - [Selectors](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#selectors)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#wp--skip-link--target)

 This package is still experimental. “Experimental” means this is an early implementation
subject to drastic and breaking changes.

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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#installation)󠁿

Install the module

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

## 󠀁[Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#usage)󠁿

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

    ```javascript
    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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#api-reference)󠁿

### 󠀁[Actions](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#actions)󠁿

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

#### 󠀁[addItems](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#retryitem)󠁿

Retries a failed item in the queue.

_Parameters_

 * _id_ `QueueItemId`: Item ID.

#### 󠀁[scheduleRetry](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#selectors)󠁿

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

#### 󠀁[getItems](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#getitems)󠁿

Returns all items currently being uploaded.

_Parameters_

 * _state_ `State`: Upload state.

_Returns_

 * `QueueItem[]`: Queue items.

#### 󠀁[getSettings](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#getsettings)󠁿

Returns the media upload settings.

_Parameters_

 * _state_ `State`: Upload state.

_Returns_

 * `Settings`: Settings

#### 󠀁[isUploading](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#isuploading)󠁿

Determines whether any upload is currently in progress.

_Parameters_

 * _state_ `State`: Upload state.

_Returns_

 * `boolean`: Whether any upload is currently in progress.

#### 󠀁[isUploadingById](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-upload-media/?output_format=md#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.

First published

January 7, 2025

Last updated

October 9, 2026

Edit article

[ Improve it on GitHub: @wordpress/upload-media ](https://github.com/WordPress/gutenberg/edit/trunk/packages/upload-media/README.md)

[  Previous: @wordpress/undo-manager](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-undo-manager/)

[  Next: @wordpress/url](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-url/)