New `registerInserterMediaCategory` API
## Metadata
- Author: [[Make WordPress Core]]
- Full Title: New `registerInserterMediaCategory` API
- Category: #articles
- Document Note: ---
tags:
- #WordPress
- #BlockEditor
- #Media
- #APIs
- #DeveloperExperience
- #OpenSource
- #Accessibility
Author: Make WordPress Core (Nik Tsekouras)
Source: WordPress.org
Reference: https://make.wordpress.org/core/2023/10/16/new-registerinsertermediacategory-api/
date created: 2025-08-23 00:00
---
# Title: New registerInserterMediaCategory API (WordPress 6.4)
## Table of Contents:
- 🔗 [References](#-references)
- 📝 [Summary](#-summary)
- 📖 [Main Content](#-main-content)
- 🗒️ [Notes](#-notes)
- 📖 [References](#-references-1)
- 🗣️ [Paraphrase](#-paraphrase)
- 📰 [Newsletter](#-newsletter)
- ✅ [Action Items](#-action-items)
- 🧪 [Hypotheses](#-hypotheses)
- 📊 [Methodology](#-methodology)
- ❓ [Questions](#-questions)
- 🔮 [Future Research](#-future-research)
- 💡 [Implications](#-implications)
- 🧠 [Learning Styles Assessment](#-learning-styles-assessment)
- 📊 [Accessibility Assessment](#-accessibility-assessment)
- 🌍 [DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment](#-deib-diversity-equity-inclusion-and-belonging-assessment)
- ✅ [Logical validity](#-logical-validity)
- 🔍 [DARVO Analysis](#-darvo-analysis)
- 🔍 [SEO Evaluation](#-seo-evaluation)
- 🎯 [Conclusion](#-conclusion)
### References:
- “From WordPress 6.4, extenders can register their own inserter media categories and provide users with more options from which to choose.”
- “Every inserter media category should have a unique name property... best to prefix this. Additionally, each category should have a unique label (labels.name).”
- Example code shows registering a category and fetching external images, including parameter mapping and returning InserterMediaItem-compatible objects.
Direct links to code/sections:
- API Announcement and overview: https://make.wordpress.org/core/2023/10/16/new-registerinsertermediacategory-api/
- Example implementation (Openverse-based): https://make.wordpress.org/core/2023/10/16/new-registerinsertermediacategory-api/
## 📝 Summary:
WordPress 6.4 introduces registerInserterMediaCategory, enabling plugins to add custom media sources to the block editor’s Media tab in the inserter. While core media categories are private (not modifiable via public updateSettings), extenders can add new categories, define labels, indicate media type, implement an async fetch that maps query parameters to the external API, and optionally provide reporting URLs. Each category must have a unique, prefixed name and label. The example leverages Openverse patterns, demonstrating how to transform external results into InserterMediaItem structures and mark them as isExternalResource.
## 📖 Main Content:
The new API empowers developers to:
- Register a custom media category in the block editor’s inserter, broadening content discovery beyond core sources.
- Control how media items are fetched via an async fetch function that:
- Accepts standard inserter queries (e.g., per_page, search),
- Maps them to the target API’s parameters,
- Returns properly shaped media items with fields like sourceId, previewUrl, and cleared id (to avoid collision with WordPress attachment IDs).
- Provide getReportUrl for user reporting/attribution flows and flag external resources with isExternalResource.
- Respect constraints: core media categories remain private; only the Openverse category can be toggled via enableOpenverseMediaCategory.
Developer considerations:
- Namespacing: Prefix name to avoid collisions.
- UX consistency: Supply clear labels and search_items text for discoverability.
- Performance: Implement efficient fetching, paging, and caching to keep the inserter snappy.
- Compliance: Mind licensing, attribution, and user reporting paths when surfacing external media.
Key excerpt:
- “Extenders can only add new inserter media categories… except for being able to disable the Openverse media category with enableOpenverseMediaCategory.”
- “Every inserter media category should have a unique name… Additionally, each category should have a unique label…”
### 🗒️ Notes
- Scope and intent
- Adds new “media categories” to the block inserter; not a replacement for Media Library but an extender-friendly entry point.
- Core categories are private; only additive customization is allowed.
- API surface
- wp.data.dispatch('core/block-editor').registerInserterMediaCategory({ ... }).
- Required: unique name, labels.name, mediaType, fetch().
- Optional: getReportUrl, isExternalResource, labels.search_items.
- Data contract
- Map inserter query to remote API (e.g., per_page -> page_size, search -> q).
- Return array of InserterMediaItem-like objects:
- Clear result.id; set sourceId to preserve remote ID.
- Provide previewUrl and caption if available.
- Example pattern
- Demonstrates defaultArgs (e.g., license filters), header user agent, and building URL with URLSearchParams.
- Controls and limitations
- Cannot modify or reorder core’s private categories.
- Can disable Openverse via enableOpenverseMediaCategory.
- UX and governance
- Clear naming and labeling are crucial for discoverability.
- Consider licensing, attribution, and reporting workflows (getReportUrl).
- Security and performance
- Validate and sanitize queries sent to external APIs.
- Implement pagination and caching to avoid slow inserter performance.
## 📖 References:
- WordPress Core Dev Note: New registerInserterMediaCategory API: https://make.wordpress.org/core/2023/10/16/new-registerinsertermediacategory-api/
- Openverse API docs (context on example mapping): https://api.openverse.engineering/v1/
## 🗣️ Paraphrase:
1) Original idea: “From WordPress 6.4, extenders can register their own inserter media categories and provide users with more options from which to choose.”
Paraphrase: Starting in 6.4, plugins can add their own media sources directly in the block inserter, expanding the choices available when searching or browsing media.
2) Original idea: “Every inserter media category should have a unique name… best to prefix this. Additionally, each category should have a unique label…”
Paraphrase: Each category must use a distinct, preferably prefixed identifier and a non-overlapping, human-readable label to avoid confusion and ensure proper internal handling.
## 📰 Newsletter:
This week in WordPress: Learn faster, build smarter. WordPress 6.4 ships registerInserterMediaCategory—so plugin authors can add external media sources right into the block inserter. Think custom stock libraries, design systems, or DAM integrations—without leaving the editor. Pro tips: prefix your category name, map search parameters cleanly, and return InserterMediaItem-safe objects (move remote id to sourceId, clear id). Bonus: add getReportUrl for user-friendly reporting and mark isExternalResource for clarity. While you can’t tweak core’s private categories, you can toggle Openverse via enableOpenverseMediaCategory. Want to practice? Try mapping per_page → page_size and search → q against Openverse’s API. For learners: brush up on REST, URLSearchParams, and fetch handling. Community shoutouts to extenders experimenting with ethical licensing and attribution. If you’re shipping a new media source, reply with a link—we’ll feature our favorites next issue. Read more on the WordPress developer note: New registerInserterMediaCategory API.
## ✅ Action Items:
A tailored prompt for aligning articles with your Developer Advocate and OSPO goals:
- Prompt: “Analyze how this WordPress change advances open-source contributor experience, educational clarity, and sustainable community practices. Identify:
1) Contributor pathways the change enables (e.g., plugin authors, educators, docs contributors);
2) Required educational assets (tutorials, samples, workshops) for onboarding diverse skill levels (PHP/JS/Gutenberg);
3) Governance and transparency touchpoints (naming conventions, API contracts, deprecation strategy);
4) Inclusive design and accessibility implications for creators and end-users;
5) Funding and sustainability angles (maintenance burden, API quotas, licensing/attribution);
6) Metrics to evaluate adoption and community health;
7) How this maps to OSPO pillars: policy, enablement, co
- Summary: From WordPress 6.4, extenders have the ability to register their own inserter media categories, expanding the options available to users. However, extenders can only add new categories and cannot update the core media categories. Each inserter media category should have a unique name and label. The example provided demonstrates how to register a new category and update the names used. It also includes information on the interfaces and documentation pages related to media categories.
- URL: https://make.wordpress.org/core/2023/10/16/new-registerinsertermediacategory-api/
From WordPress 6.4, extenders can register their own inserter media categories and provide users with more options from which to choose.
Even though the core’s media categories are a block editor setting, it is a private one, which means it cannot be updated through the public `updateSettings` action. Extenders can only add new inserter media categories, and they don’t have any control over the core media categories, except for being able to disable the `Openverse` media category with `enableOpenverseMediaCategory` block editor setting.
Every inserter media category should have a unique `name` property, which is used internally like an id, so it’s best to prefix this. Additionally, each category should have a unique label to be differentiated from the other ones(`labels.name` property).
You can read more about the used interfaces that a media category, media item and the request for media should abide to, on the [documentation pages](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-block-editor/#registerinsertermediacategory).
The example uses the `Openverse` category object and just updates the names used:
```
wp.data.dispatch( 'core/block-editor' ).registerInserterMediaCategory( {
name: 'my-new-category',
labels: {
name: 'My new category',
search_items: 'Search Openverse',
},
mediaType: 'image',
async fetch( query = {} ) {
const defaultArgs = {
mature: false,
excluded_source: 'flickr,inaturalist,wikimedia',
license: 'pdm,cc0',
};
const finalQuery = { ...query, ...defaultArgs };
// Sometimes you might need to map the supported request params
// according to `InserterMediaRequest`.
// interface. In this example the `search` query param is named `q`.
const mapFromInserterMediaRequest = {
per_page: 'page_size',
search: 'q',
};
const url = new URL( 'https://api.openverse.engineering/v1/images/' );
Object.entries( finalQuery ).forEach( ( [ key, value ] ) => {
const queryKey = mapFromInserterMediaRequest[ key ] || key;
url.searchParams.set( queryKey, value );
} );
const response = await window.fetch( url, {
headers: {
'User-Agent': 'WordPress/inserter-media-fetch',
},
} );
const jsonResponse = await response.json();
const results = jsonResponse.results;
return results.map( ( result ) => ( {
...result,
// If your response result includes an `id` prop
// that you want to access later, it should
// be mapped to `InserterMediaItem`'s `sourceId` prop.
// This can be useful if you provide a report URL getter.
// Additionally you should always clear the `id` value of
// your response results because it is used to identify
// WordPress media items.
sourceId: result.id,
id: undefined,
caption: result.caption,
previewUrl: result.thumbnail,
} ) );
},
getReportUrl: ( { sourceId } ) =>
`https://wordpress.org/openverse/image/${ sourceId }/report/`,
isExternalResource: true,
} );
```, New `registerInserterMediaCategory` API, Make WordPress Core, 01hcwnbcxtp6ca940fkm4pzg6b.