Title: @wordpress/media-utils
Published: March 9, 2021
Last modified: November 5, 2026

---

# @wordpress/media-utils

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#installation)
 * [API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#api)
    - [Attachment](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#attachment)
    - [MediaUpload](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#mediaupload)
    - [privateApis](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#privateapis)
    - [RestAttachment](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#restattachment)
    - [SubSizeData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#subsizedata)
    - [transformAttachment](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#transformattachment)
    - [uploadMedia](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#uploadmedia)
    - [validateFileSize](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#validatefilesize)
    - [validateMimeType](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#validatemimetype)
    - [validateMimeTypeForUser](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#validatemimetypeforuser)
 * [Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#usage)
    - [uploadMedia](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#uploadmedia-2)
    - [MediaUpload](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#mediaupload-2)
 * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#contributing-to-this-package)

The media utils package provides a set of artifacts to abstract media functionality
that may be useful in situations where there is a need to deal with media uploads
or with the media library, e.g., artifacts that extend or implement a block-editor.

This package is meant to be used by the WordPress core. It may not work as expected
outside WordPress usages.

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

Install the module

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

_This package assumes that your code will run in an **ES2015+** environment. If 
you’re using an environment that has limited or no support for such language features
and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
in your code._

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

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

Undocumented declaration.

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

Undocumented declaration.

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

Private `@wordpress/media-utils` APIs.

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

Undocumented declaration.

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

Undocumented declaration.

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

Transforms an attachment object from the REST API shape into the shape expected 
by the block editor and other consumers.

_Parameters_

 * _attachment_ `RestAttachment`: REST API attachment object.

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

Upload a media file when the file upload button is activated or when adding a file
to the editor via drag & drop.

_Parameters_

 * _$0_ `UploadMediaArgs`: Parameters object passed to the function.
 * _$0.allowedTypes_ `UploadMediaArgs[ 'allowedTypes' ]`: Array with the types of
   media that can be uploaded, if unset all types are allowed.
 * _$0.additionalData_ `UploadMediaArgs[ 'additionalData' ]`: Additional data to
   include in the request.
 * _$0.filesList_ `UploadMediaArgs[ 'filesList' ]`: List of files.
 * _$0.maxUploadFileSize_ `UploadMediaArgs[ 'maxUploadFileSize' ]`: Maximum upload
   size in bytes allowed for the site.
 * _$0.onError_ `UploadMediaArgs[ 'onError' ]`: Function called when an error happens.
 * _$0.onFileChange_ `UploadMediaArgs[ 'onFileChange' ]`: Function called each time
   a file or a temporary representation of the file is available.
 * _$0.wpAllowedMimeTypes_ `UploadMediaArgs[ 'wpAllowedMimeTypes' ]`: List of allowed
   mime types and file extensions.
 * _$0.signal_ `UploadMediaArgs[ 'signal' ]`: Abort signal.
 * _$0.multiple_ `UploadMediaArgs[ 'multiple' ]`: Whether to allow multiple files
   to be uploaded.

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

Verifies whether the file is within the file upload size limits for the site.

_Parameters_

 * _file_ `File`: File object.
 * _maxUploadFileSize_ `number`: Maximum upload size in bytes allowed for the site.

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

Verifies if the caller (e.g. a block) supports this mime type.

_Parameters_

 * _file_ `File`: File object.
 * _allowedTypes_ `string[]`: List of allowed mime types.

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

Verifies if the user is allowed to upload this mime type.

_Parameters_

 * _file_ `File`: File object.
 * _wpAllowedMimeTypes_ `Record< string, string > | null`: List of allowed mime 
   types and file extensions.

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

### 󠀁[uploadMedia](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#uploadmedia-2)󠁿

Media upload util is a function that allows the invokers to upload files to the 
WordPress media library.
 As an example, provided that `myFiles` is an array of 
file objects, `handleFileChange` on onFileChange is a function that receives an 
array of objects containing the description of WordPress media items and `handleFileError`
is a function that receives an object describing a possible error, the following
code uploads a file to the WordPress media library:

    ```javascript
    wp.mediaUtils.utils.uploadMedia( {
        filesList: myFiles,
        onFileChange: handleFileChange,
        onError: handleFileError,
    } );
    ```

The following code uploads a file named foo.txt with foo as content to the media
library and alerts its URL:

    ```javascript
    wp.mediaUtils.utils.uploadMedia( {
        filesList: [ new File( [ 'foo' ], 'foo.txt', { type: 'text/plain' } ) ],
        onFileChange: ( [ fileObj ] ) => alert( fileObj.url ),
        onError: console.error,
    } );
    ```

Beware that first onFileChange is called with temporary blob URLs and then with 
the final URL’s this allows to show the result in an optimistic UI as if the upload
was already completed. E.g.: when uploading an image, one can show the image right
away in the UI even before the upload is complete.

### 󠀁[MediaUpload](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#mediaupload-2)󠁿

Media upload component provides a UI button that allows users to open the WordPress
media library. It is normally used in conjunction with the filter `editor.MediaUpload`.

The component follows the interface specified in [https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md),
and more details regarding its usage can be checked there.

## 󠀁[Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-media-utils/?output_format=md#contributing-to-this-package)󠁿

This is an individual package that’s part of the Gutenberg project. The project 
is organized as a monorepo. It’s made up of multiple self-contained software packages,
each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) as well as other software
projects.

To find out more about contributing to this package or Gutenberg as a whole, please
read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

First published

March 9, 2021

Last updated

November 5, 2026

Edit article

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

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

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