); }, save: () => { const blockProps = useBlockProps.save(); const innerBlocksProps = useInnerBlocksProps.save(); return (

); }, } ); ``` This hook can also pass objects returned from the `useBlockProps` hook to the `useInnerBlocksProps` hook. This reduces the number of elements we need to create. ``` js import { registerBlockType } from '@wordpress/blocks'; import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor'; registerBlockType( 'gutenberg-examples/example-06', { // ... edit: () => { const blockProps = useBlockProps(); const innerBlocksProps = useInnerBlocksProps( blockProps ); return (

); }, save: () => { const blockProps = useBlockProps.save(); const innerBlocksProps = useInnerBlocksProps.save( blockProps ); return (

); }, } ); ``` The above code will render to the following markup in the editor: ``` html

``` Another benefit to using the hook approach is using the returned value, which is just an object, and deconstruct to get the react children from the object. This property contains the actual child inner blocks thus we can place elements on the same level as our inner blocks. ``` js import { registerBlockType } from '@wordpress/blocks'; import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor'; registerBlockType( 'gutenberg-examples/example-06', { // ... edit: () => { const blockProps = useBlockProps(); const { children, ...innerBlocksProps } = useInnerBlocksProps( blockProps ); return (

{ children } {/* Insert any arbitrary html here at the same level as the children */}

); }, // ... } ); ``` ``` html

``` # Extending the Query Loop block The Query Loop block is a powerful tool that allows users to cycle through a determined list of posts and display a certain set of blocks that will inherit the context of each of the posts in the list. For example, it can be set to cycle through all the posts of a certain category and for each of those posts display their featured image. And much more, of course! But precisely because the Query Loop block is so powerful and allows for great customization, it can also be daunting. Most users wouldn’t want to be presented with the full capabilities of the Query Loop block, as most users wouldn’t be familiar with the concept of a “query” and its associated technical terms. Instead, most users will likely appreciate a pre-set version of the block, with fewer settings to adjust and clearer naming. The Post List variation offered by default is a good example of this practice: the user will be using the Query Loop block without being exposed to its technicalities, and will also be more likely to discover and understand the purpose of the block. In the same manner, a lot of extenders might need a way to present bespoke versions of the block, with their own presets, additional settings and without customization options which are irrelevant to their use-case (often, for example, their custom post type). The Query Loop block offers very powerful ways to create such variations. ## Extending the block with variations By registering your own block variation with some specific Query Loop block settings, you can have finer control over how it is presented, while still being able to use the full capabilities which the Query Loop block offers underneath. If you are not familiar with block variations, learn more about them [here](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/). With the block variations API you can provide the default settings that make the most sense for your use-case. In order to have a Query Loop variation properly working, we’ll need to:\ – Register the block variation for the `core/query` block with some default values\ – Define a layout for the block variation\ – Use the `namespace` attribute in the `isActive` block variation property Let’s go on a journey, for example, of setting up a variation for a plugin which registers a `book` [custom post type](https://developer.wordpress.org/plugins/post-types/). ### 1. Offer sensible defaults Your first step would be to create a variation which will be set up in such a way to provide a block variation which will display by default a list of books instead of blog posts. The full variation code will look something like this: ``` js const MY_VARIATION_NAME = 'my-plugin/books-list'; registerBlockVariation( 'core/query', { name: MY_VARIATION_NAME, title: 'Books List', description: 'Displays a list of books', isActive: ( { namespace, query } ) => { return ( namespace === MY_VARIATION_NAME && query.postType === 'book' ); }, icon: /** An SVG icon can go here*/, attributes: { namespace: MY_VARIATION_NAME, query: { perPage: 6, pages: 0, offset: 0, postType: 'book', order: 'desc', orderBy: 'date', author: '', search: '', exclude: [], sticky: '', inherit: false, }, }, scope: [ 'inserter' ], } ); ``` If that sounds like a lot, don’t fret, let’s go through each of the properties here and see why they are there and what they are doing. Essentially, you would start with something like this: ``` js registerBlockVariation( 'core/query', { name: 'my-plugin/books-list', attributes: { query: { /** ...more query settings if needed */ postType: 'book', }, }, } ); ``` In this way, the users won’t have to choose the custom `postType` from the dropdown, and be already presented with the correct configuration. A variation’s `query` replaces the block’s default `query` object instead of merging into it, so include every property your variation relies on, not only the ones you change. Always set `postType`: when it’s missing, the block queries posts, both in the editor and on the front end. However, you might ask, how is a user going to find and insert this variation? Good question! To enable this, you should add: ``` js { /** ...variation properties */ scope: [ 'inserter' ], } ``` In this way, your block will show up just like any other block while the user is in the editor and searching for it. At this point you might also want to add a custom icon, title and description to your variation, just like so: ``` js { /** ...variation properties */ title: 'Books List', description: 'Displays a list of books', icon: /* Your svg icon here */, } ``` At this point, your custom variation will be virtually indistinguishable from a stand-alone block. Completely branded to your plugin, easy to discover and directly available to the user as a drop in. However, your query loop variation won’t work just yet — we still need to define a layout so that it can render properly. ### 2. Customize your variation layout Please note that the Query Loop block supports `'block'` as a string in the `scope` property. In theory, that’s to allow the variation to be picked up after inserting the block itself. Read more about the Block Variation Picker [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md). However, it is **unadvisable** to use this currently, this is due to the Query Loop setup with patterns and `scope: [ 'block' ]` variations, all of the selected pattern’s attributes will be used except for `postType` and `inherit` query properties, which will likely lead to conflicts and non-functional variations. To circumvent this, there two routes, the first one is to add your default `innerBlocks`, like so: ``` js innerBlocks: [ [ 'core/post-template', {}, [ [ 'core/post-title' ], [ 'core/post-excerpt' ] ], ], [ 'core/query-pagination' ], [ 'core/query-no-results' ], ], ``` By having `innerBlocks` in your variation you essentially skip the setup phase of Query Loop block with suggested patterns and the block is inserted with these inner blocks as its starting content. The other way would be to register patterns specific to your variation, which are going to be suggested in the setup, and replace flows of the block. The Query Loop block determines if there is an active variation of itself and if there are specific patterns available for this variation. If there are, these patterns are going to be the only ones suggested to the user, without including the default ones for the original Query Loop block. Otherwise, if there are no such patterns, the default ones are going to be suggested. In order for a pattern to be “connected” with a Query Loop variation, you should add the name of your variation prefixed with the Query Loop name (e.g. `core/query/$variation_name`) to the pattern’s `blockTypes` property. For more details about registering patterns [see here](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/). If you have not provided `innerBlocks` in your variation, there is also a way to suggest “connected” variations when the user selects `Start blank` in the setup phase. This is handled in a similar fashion with “connected” patterns, by checking if there is an active variation of Query Loop and if there are any connected variations to suggest. In order for a variation to be connected to another Query Loop variation we need to define the `scope` attribute with `['block']` as value and the `namespace` attribute defined as an array. This array should contain the names(`name` property) of any variations they want to be connected to. For example, if we have a Query Loop variation exposed to the inserter(`scope: ['inserter']`) with the name `products`, we can connect a scoped `block` variation by setting its `namespace` attribute to `['products']`. If the user selects this variation after having clicked `Start blank`, the namespace attribute will be overridden by the main inserter variation. ### 3. Making Gutenberg recognize your variation There is one slight problem you might have realized after implementing this variation: while it is transparent to the user as they are inserting it, Gutenberg will still recognize the variation as a Query Loop block at its core and so, after its insertion, it will show up as a Query Loop block in the tree view of the editor, for instance. We need a way to tell the editor that this block is indeed your specific variation. This is what the `isActive` property is made for: it’s a way to determine whether a certain variation is active based on the block’s attributes. You could use it like this: ``` js { /** ...variation properties */ isActive: ( { namespace, query } ) => { return ( namespace === MY_VARIATION_NAME && query.postType === 'book' ); }, } ``` You might be tempted to only compare the `postType` so that Gutenberg will recognize the block as your variation any time the `postType` matches `book`. This casts a net too wide, however, as other plugins might want to publish variations based on the `book` post type too, or we might just not want the variation to be recognized every time the user sets the type to `book` manually through the editor settings. That’s why the Query Loop block exposes a special attribute called `namespace`. It really doesn’t do anything inside the block implementation, and it’s used as an easy and consistent way for extenders to recognize and scope their own variation. In addition, `isActive` also accepts just an array of strings with the attributes to compare. Often, `namespace` would be sufficient, so you would use it like so: ``` js { /** ...variation properties */ attributes: { /** ...variation attributes */ namespace: 'my-plugin/books-list', }, isActive: [ 'namespace' ], } ``` Like so, Gutenberg will know that it is your specific variation only in the case it matches your custom namespace! So convenient! ## Extending the query Even with all of this, your custom post type might have unique requirements: it might support certain custom attributes that you might want to filter and query for, or some other query parameters might be irrelevant or even completely unsupported! We have build the Query Loop block with such use-cases in mind, so let’s see how you can solve this problem. ### Disabling irrelevant or unsupported query controls Let’s say you don’t use at all the `sticky` attribute in your books, so that would be totally irrelevant to the customization of your block. In order to not confuse the users as to what a setting might do, and only exposing a clear UX to them, we want this control to be unavailable. Furthermore, let’s say that you don’t use the `author` field at all, which generally indicates the person who has added that post to the database, instead you use a custom `bookAuthor` field. As such, not only keeping the `author` filter would be confusing, it would outright “break” your query. For this reason, the Query Loop block variations support a property called `allowedControls`, which accepts an array of keys of the controls we want to display on the inspector sidebar. By default, we accept all the controls, but as soon as we provide an array to this property, we want to specify only the controls which are going to be relevant for us! As of Gutenberg version 14.2, the following controls are available: - `inherit` – Shows the toggle switch for allowing the query to be inherited directly from the template. - `postType` – Shows a dropdown of available post types. - `order` – Shows a dropdown to select the order of the query. - `sticky` – Shows a dropdown to select how to handle sticky posts. - `taxQuery` – Shows available taxonomies filters for the currently selected post type, including both inclusion and exclusion controls for each taxonomy. - `author` – Shows an input field to filter the query by author. - `search` – Shows an input field to filter the query by keywords. - `format` – Shows an input field to filter the query by array/collection of [formats](https://developer.wordpress.org/advanced-administration/wordpress/post-formats/#supported-formats). - `parents` – Shows an input field to filter the query using parent(s) entity. In our case, the property would look like this: ``` js { /** ...variation properties */ allowedControls: [ 'inherit', 'order', 'taxQuery', 'search' ], } ``` If you want to hide all the above available controls, you can set an empty array as a value of `allowedControls`. Notice that we have also disabled the `postType` control. When the user selects our variation, why show them a confusing dropdown to change the post type? On top of that it might break the block as we can implement custom controls, as we’ll see shortly. ### Understanding the `taxQuery` structure The `taxQuery` attribute supports both inclusion and exclusion of taxonomy terms. The structure looks like this: ``` js { query: { taxQuery: { include: { category: [1, 2, 3], // Include posts with these category IDs. post_tag: [10, 20] // Include posts with these tag IDs. }, exclude: { category: [5, 6], // Exclude posts with these category IDs. post_tag: [15] // Exclude posts with these tag IDs. } } } } ``` When you use the `taxQuery` control in your variation, users will see both “\[Taxonomy\]” (inclusion) and “Exclude: \[Taxonomy\]” controls for each applicable taxonomy. The inclusion and exclusion are mutually exclusive in the UI – terms selected in one won’t appear as suggestions in the other. ### Adding additional controls Because our plugin uses custom attributes that we need to query, we want to add our own controls to allow the users to select those instead of the ones we have just disabled from the core inspector controls. We can do this via a [React HOC](https://reactjs.org/docs/higher-order-components.html) hooked into a [block filter](https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/), like so: ``` jsx import { InspectorControls } from '@wordpress/block-editor'; export const withBookQueryControls = ( BlockEdit ) => ( props ) => { // We only want to add these controls if it is our variation, // so here we can implement a custom logic to check for that, similar // to the `isActive` function described above. // The following assumes that you wrote a custom `isMyBooksVariation` // function to handle that. return isMyBooksVariation( props ) ? ( <> { /** Our custom component */ } ) : ( ); }; addFilter( 'editor.BlockEdit', 'core/query', withBookQueryControls ); ``` Of course, you’ll be responsible for implementing the logic of your control (you might want to take a look at [`@wordpress/components`](https://www.npmjs.com/package/@wordpress/components) to make your controls fit seamlessly within the Gutenberg UI). Any extra parameter you assign within the `query` object inside the blocks attributes can be used to create a custom query according to your needs, with a little extra effort. Currently, you’ll likely have to implement slightly different paths to make the query behave correctly both on the front-end side (i.e. on the end user’s side) and to show the correct preview on the editor side. ``` js { /** ...variation properties */ attributes: { /** ...variation attributes */ query: { /** ...more query settings if needed */ postType: 'book', /** Our custom query parameter */ bookAuthor: 'J. R. R. Tolkien' } } } ``` ### Making your custom query work on the front-end side The Query Loop block functions mainly through the Post Template block which receives the attributes and builds the query from there. Other first-class children of the Query Loop block (such as the Pagination block) behave in the same way. They build their query and then expose the result via the filter [`query_loop_block_query_vars`](https://developer.wordpress.org/reference/hooks/query_loop_block_query_vars/). You can hook into that filter and modify your query accordingly. Just make sure you don’t cause side-effects to other Query Loop blocks by at least checking that you apply the filter only to your variation! ``` php if( 'my-plugin/books-list' === $block[ 'attrs' ][ 'namespace' ] ) { add_filter( 'query_loop_block_query_vars', function( $query ) { /** You can read your block custom query parameters here and build your query */ }, ); } ``` (In the code above, we assume you have some way to access the block, for example within a [`pre_render_block`](https://developer.wordpress.org/reference/hooks/pre_render_block/) filter, but the specific solution can be different depending on the use-case, so this is not a firm recommendation). ### Making your custom query work on the editor side To finish up our custom variation, we might want the editor to react to changes in our custom query and display an appropriate preview accordingly. This is not required for a functioning block, but it enables a fully integrated user experience for the consumers of your block. The Query Loop block fetches its posts to show the preview using the [WordPress REST API](https://developer.wordpress.org/rest-api/). Any extra parameter added to the `query` object will be passed as a query argument to the API. This means that these extra parameters should be either supported by the REST API, or be handled by custom filters such as the [`rest_{$this->post_type}_query`](https://developer.wordpress.org/reference/hooks/rest_this-post_type_query/) filter which allows you to hook into any API request for your custom post type. Like so: ``` php add_filter( 'rest_book_query', function( $args, $request ) { /** We can access our custom parameters from here */ $book_author = $request->get_param( 'bookAuthor' ); /** ...your custom query logic */ } ); ``` And, just like that, you’ll have created a fully functional variation of the Query Loop block! # Building a custom block editor The WordPress block editor is a powerful tool that allows you to create and format content in various ways. It is powered, in part, by the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-block-editor/) package, which is a JavaScript library that provides the core functionality of the editor. This package can also be used to create custom block editors for virtually any other web application. This means that you can use the same blocks and block editing experience outside of WordPress. WordPress block editor showing content blocks and editing options

WordPress block editor showing content blocks and editing options

This flexibility and interoperability makes blocks a powerful tool for building and managing content across multiple applications. It also makes it simpler for developers to create content editors that work best for their users. This guide covers the basics of creating your first custom block editor. ## Introduction With its many packages and components, the Gutenberg codebase can be daunting at first. But at its core, it’s all about managing and editing blocks. So if you want to work on the editor, it’s essential to understand how block editing works at a fundamental level. This guide will walk you through building a fully functioning, custom block editor “instance” within WordPress. Along the way, we’ll introduce you to the key packages and components, so you can see how the block editor works under the hood. By the end of this article, you will have a solid understanding of the block editor’s inner workings and be well on your way to creating your own block editor instances.

The code used throughout this guide is available for download in the [accompanying WordPress plugin](https://github.com/getdave/standalone-block-editor). The demo code in this plugin is an essential resource.

## Code syntax The code snippets in this guide use JSX syntax. However, you could use plain JavaScript if you prefer. However, once familiar with JSX, many developers find it easier to read and write, so all code examples in the Block Editor Handbook use this syntax. ## What you’re going to be building Throughout this guide, you will create an (almost) fully functioning block editor instance. The result will look something like this: The Standalone Editor instance populated with example Blocks within a custom WordPress admin page

The Standalone Editor instance populated with example Blocks within a custom WordPress admin page

While it looks similar, this editor will not be the same *Block Editor* you are familiar with when creating posts and pages in WordPress. Instead, it will be an entirely custom instance that will live within a custom WordPress admin page called “Block Editor.” The editor will have the following features: - Ability to add and edit all Core blocks. - Familiar visual styles and main/sidebar layout. - *Basic* block persistence between page reloads. ## Plugin setup and organization The custom editor is going to be built as a WordPress plugin. To keep things simple, the plugin will be named `Standalone Block Editor Demo` because that is what it does. The plugin file structure will look like this: Project directory listing with configuration and source files

Project directory listing with configuration and source files

Here is a brief summary of what’s going on: - `plugin.php` – Standard plugin “entry” file with comment meta data, which requires `init.php`. - `init.php` – Handles the initialization of the main plugin logic. - `src/` (directory) – This is where the JavaScript and CSS source files will live. These files are *not* directly enqueued by the plugin. - `webpack.config.js` – A custom Webpack config extending the defaults provided by the [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) npm package to allow for custom CSS styles (via Sass). The only item not shown above is the `build/` directory, which is where the *compiled* JS and CSS files are outputted by `@wordpress/scripts`. These files are enqueued by the plugin separately.

Throughout this guide, filename references will be placed in a comment at the top of each code snippet so you can follow along.

With the basic file structure in place, let’s look at what packages will be needed. ## The “Core” of the editor While the WordPress Editor is comprised of many moving parts, at its core is the [`@wordpress/block-editor`](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-block-editor/) package, which is best summarized by its own `README` file: > This module allows you to create and use standalone block editors. Perfect, this is the main package you will use to create the custom block editor instance. But first, you need to create a home for the editor. ## Creating the custom “Block Editor” page Let’s begin by creating a custom page within WordPress admin that will house the custom block editor instance.

If you’re already comfortable with the process of creating custom admin pages in WordPress, you might want to [skip ahead](#registering-and-rendering-the-custom-block-editor).

### Registering the page To do this, you need to [register a custom admin page](https://developer.wordpress.org/reference/functions/add_menu_page/) using the standard WordPress [`add_menu_page()`](https://developer.wordpress.org/reference/functions/add_menu_page/) helper: ``` php // File: init.php add_menu_page( 'Standalone Block Editor', // Visible page name 'Block Editor', // Menu label 'edit_posts', // Required capability 'getdavesbe', // Hook/slug of page 'getdave_sbe_render_block_editor', // Function to render the page 'dashicons-welcome-widgets-menus' // Custom icon ); ``` The `getdave_sbe_render_block_editor` function will be used to render the contents of the admin page. As a reminder, the source code for each step is available in the [accompanying plugin](https://github.com/getdave/standalone-block-editor). ### Adding the target HTML Since the block editor is a React-powered application, you need to output some HTML into the custom page where JavaScript can render the block editor. Let’s use the `getdave_sbe_render_block_editor` function referenced in the step above. ``` php // File: init.php function getdave_sbe_render_block_editor() { ?>

Loading Editor...

` component into the waiting `

` on the custom admin page. ``` jsx domReady( function () { const root = createRoot( document.getElementById( 'getdave-sbe-block-editor' ) ); const settings = window.getdaveSbeSettings || {}; registerCoreBlocks(); root.render( ); } ); ```

It is possible to render the editor from PHP without creating an unnecessary JS global. Check out the [Edit Site](https://href.li/?https://github.com/WordPress/gutenberg/blob/c6821d7e64a54eb322583a35daedc6c192ece850/lib/edit-site-page.php#L135) package in the Gutenberg plugin for an example of this.

## Reviewing the `` component Let’s take a closer look at the `` component that was used in the code above and lives in `src/editor.js` of the [companion plugin](https://github.com/getdave/standalone-block-editor). Despite its name, this is not the actual core of the block editor. Rather, it is a *wrapper* component that will contain the components that form the custom editor’s main body. ### Dependencies The first thing to do inside `` is to pull in some dependencies. ``` jsx // File: src/editor.js import Notices from 'components/notices'; import Header from 'components/header'; import Sidebar from 'components/sidebar'; import BlockEditor from 'components/block-editor'; ``` The most important of these are the internal components `BlockEditor` and `Sidebar`, which will be covered shortly. The remaining components consist mostly of static elements that form the editor’s layout and surrounding user interface (UI). These elements include the header and notice areas, among others. ### Editor render With these components available, you can define the `` component. ``` jsx // File: src/editor.js function Editor( { settings } ) { return (

); } ``` In this process, the core of the editor’s layout is being scaffolded, along with a few specialized [context providers](https://react.dev/reference/react/createContext#provider) that make specific functionality available throughout the component hierarchy. Let’s examine these in more detail: - `` – Enables the use of [dropzones for drag and drop functionality](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/components/src/drop-zone) - `` – Provides a “snack bar” Notice that will be rendered if any messages are dispatched to the `core/notices` store - `

` – Renders the static title “Standalone Block Editor” at the top of the editor UI - `` – The custom block editor component ### Keyboard navigation With this basic component structure in place, the only remaining thing left to do\ is wrap everything in the [`navigateRegions` HOC](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/components/src/higher-order/navigate-regions) to provide keyboard navigation between the different “regions” in the layout. ``` jsx // File: src/editor.js export default navigateRegions( Editor ); ``` ## The custom `` Now the core layouts and components are in place. It’s time to explore the custom implementation of the block editor itself. The component for this is called ``, and this is where the magic happens. Opening `src/components/block-editor/index.js` reveals that it’s the most complex component encountered thus far. A lot going on, so start by focusing on what is being rendered by the `` component: ``` js // File: src/components/block-editor/index.js return (

); ``` The key components are `` and ``. Let’s examine these. ### Understanding the `` component [``](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/provider) is one of the most important components in the hierarchy. It establishes a new block editing context for a new block editor. As a result, it is *fundamental* to the entire goal of this project. The children of `` comprise the UI for the block editor. These components then have access to data (via `Context`), enabling them to *render* and *manage* the blocks and their behaviors within the editor. ``` jsx // File: src/components/block-editor/index.js ``` #### `BlockEditor` props You can see that `` accepts an array of (parsed) block objects as its `value` prop and, when there’s a change detected within the editor, calls the `onChange` and/or `onInput` handler prop (passing the new Blocks as an argument). Internally it does this by subscribing to the provided `registry` (via the [`withRegistryProvider` HOC](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/provider/index.js#L158)), listening to block change events, determining whether the block changing was persistent, and then calling the appropriate `onChange|Input` handler accordingly. For the purposes of this simple project, these features allow you to: - Store the array of current blocks in state as `blocks`. - Update the `blocks` state in memory on `onInput` by calling the hook setter\ `updateBlocks(blocks)`. - Handle basic persistence of blocks into `localStorage` using `onChange`. This is [fired when block updates are considered “committed”](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/provider#onchange). It’s also worth recalling that the component accepts a `settings` property. This is where you will add the editor settings inlined earlier as JSON within `init.php`. You can use these settings to configure features such as custom colors, available image sizes, and [much more](https://github.com/WordPress/gutenberg/tree/4c472c3443513d070a50ba1e96f3a476861447b3/packages/block-editor#SETTINGS_DEFAULTS). ### Understanding the `` component Alongside `` the next most interesting component is [``](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/block-list/index.js). This is one of the most important components as it’s role is to **render a list of blocks into the editor**. It does this in part thanks to being placed as a child of ``, which affords it full access to all information about the state of the current blocks in the editor. #### How does `BlockList` work? Under the hood, `` relies on several other lower-level components in order to render the list of blocks. The hierarchy of these components can be *approximated* as follows: ``` jsx // Pseudo code for example purposes only. /* renders a list of blocks from the rootClientId. */ /* renders a single block from the BlockList. */ /* renders the standard editable area of a block. */ /* renders the block UI as defined by its `edit()` implementation. */ ``` Here is roughly how this works together to render the list of blocks: - `` loops over all the block `clientIds` and\ renders each via [``](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/block-list/block.js). - ``, in turn, renders the individual block\ using its own subcomponent [``](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-edit/index.js). - Finally, the [block itself](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-edit/edit.js) is rendered using the `Component` placeholder component. The `@wordpress/block-editor` package components are among the most complex and involved. Understanding them is crucial if you want to grasp how the editor functions at a fundamental level. Studying these components is strongly advised. ## Reviewing the sidebar Also within the render of the ``, is the `` component. ``` jsx // File: src/components/block-editor/index.js return (

/* <-- SIDEBAR */

); ``` This is used, in part, to display advanced block settings via the `` component. ``` jsx ``` However, the keen-eyed readers amongst you will have already noted the presence of a `` component within the `` (`src/editor.js`) component’s\ layout: ``` jsx // File: src/editor.js

// <-- What's this? ``` Opening the `src/components/sidebar/index.js` file, you can see that this is, in fact, the component rendered within `` above. However, the implementation utilises\ Slot/Fill to expose a `Fill` (``), which is subsequently imported and rendered inside of the `` component (see above). With this in place, you then can render `` as a child of the `Sidebar.InspectorFill`. This has the result of allowing you to keep `` within the React context of `` whilst allowing it to be rendered into the DOM in a separate location (i.e. in the ``). This might seem overly complex, but it is required in order for `` to have access to information about the current block. Without Slot/Fill, this setup would be extremely difficult to achieve. And with that you have covered the render of you custom ``.

[``](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-inspector/index.js)\ itself actually renders a `Slot` for [``](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-editor/src/components/inspector-controls). This is what allows you [render](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-library/src/paragraph/edit.js#L127) a `` component inside\ the `edit()` definition for your block and have\ it display within the editor’s sidebar. Exploring this component in more detail is recommended.

## Block Persistence You have come a long way on your journey to create a custom block editor. But there is one major area left to touch upon – block persistence. In other words, having your\ blocks saved and available *between* page refreshes. WordPress custom block editor interface with various content blocks and editing options

WordPress custom block editor interface with various content blocks and editing options

As this is only an *experiment*, this guide has opted to utilize the browser’s `localStorage` API to handle saving block data. In a real-world scenario, you would likely choose a more reliable and robust system (e.g. a database). That said, let’s take a closer look at how to handle save blocks. ### Storing blocks in state Looking at the `src/components/block-editor/index.js` file, you will notice that some state has been created to store the blocks as an array: ``` jsx // File: src/components/block-editor/index.js const [ blocks, updateBlocks ] = useState( [] ); ``` As mentioned earlier, `blocks` is passed to the “controlled” component `` as its `value` prop. This “hydrates” it with an initial set of blocks. Similarly, the `updateBlocks` setter is hooked up to the `onInput` callback on ``, which ensures that the block state is kept in sync with changes made to blocks within the editor. ### Saving block data If you now turn your attention to the `onChange` handler, you will notice it is hooked up to a function `persistBlocks()` which is defined as follows: ``` js // File: src/components/block-editor/index.js function persistBlocks( newBlocks ) { updateBlocks( newBlocks ); window.localStorage.setItem( 'getdavesbeBlocks', serialize( newBlocks ) ); } ``` This function accepts an array of “committed” block changes and calls the state setter `updateBlocks`. It also stores the blocks within LocalStorage under the key `getdavesbeBlocks`. In order to achieve this, the block data is serialized into [Gutenberg “Block Grammar”](https://developer.wordpress.org/block-editor/principles/key-concepts/#blocks) format, meaning it can be safely stored as a string. If you open DeveloperTools and inspect the LocalStorage you will see serialized block data stored and updated as changes occur within the editor. Below is an example of the format:

An experiment with a standalone Block Editor in the WordPress admin

This is an experiment to discover how easy (or otherwise) it is to create a standalone instance of the Block Editor in the WordPress admin.

### Retrieving previous block data Having persistence in place is all well and good, but it’s only useful if that data is retrieved and *restored* within the editor upon each full page reload. Accessing data is a side effect, so you must use the `useEffect` hook to handle this. ``` jsx // File: src/components/block-editor/index.js useEffect( () => { const storedBlocks = window.localStorage.getItem( 'getdavesbeBlocks' ); if ( storedBlocks && storedBlocks.length ) { updateBlocks( () => parse( storedBlocks ) ); createInfoNotice( 'Blocks loaded', { type: 'snackbar', isDismissible: true, } ); } }, [] ); ``` This handler: - Grabs the serialized block data from local storage. - Converts the serialized blocks back to JavaScript objects using the `parse()` utility. - Calls the state setter `updateBlocks` causing the `blocks` value to be updated in state to reflect the blocks retrieved from LocalStorage. As a result of these operations, the controlled `` component is updated with the blocks restored from LocalStorage, causing the editor to show these blocks. Finally, you will want to generate a notice – which will display in the `` component as a “snackbar” notice – to indicate that the blocks have been restored. ## Wrapping up Congratulations for completing this guide. You should now have a better understanding of how the block editor works under the hood. The full code for the custom block editor you have just built is [available on GitHub](https://github.com/getdave/standalone-block-editor). Download and try it out for yourself. Experiment, then and take things even further. # Block Design The following are best practices for designing a new block, with recommendations and detailed descriptions of existing blocks to illustrate our approach to creating blocks. ## Best Practices ### The primary interface for a block is the content area of the block Since the block itself represents what will actually appear on the site, interaction here hews closest to the principle of direct manipulation and will be most intuitive to the user. This should be thought of as the primary interface for adding and manipulating content and adjusting how it is displayed. There are two ways of interacting here: 1. The placeholder content in the content area of the block can be thought of as a guide or interface for users to follow a set of instructions or “fill in the blanks”. For example, a block that embeds content from a 3rd-party service might contain controls for signing in to that service in the placeholder. 2. After the user has added content, selecting the block can reveal additional controls to adjust or edit that content. For example, a signup block might reveal a control for hiding/showing subscriber count. However, this should be done in minimal ways, so as to avoid dramatically changing the size and display of a block when a user selects it (this could be disorienting or annoying). ### The Block Toolbar is a secondary place for required options & controls Basic block settings won’t always make sense in the context of the placeholder/content UI. As a secondary option, options that are critical to the functionality of a block can live in the block toolbar. The Block Toolbar is still highly contextual and visible on all screen sizes. One notable constraint with the Block Toolbar is that it is icon-based UI, so any controls that live in the Block Toolbar need to be ones that can effectively be communicated via an icon or icon group. ### Group Block Toolbar controls with related items The Block Toolbar groups controls in segments, hierarchically. The first segment contains block type controls, such as the block switcher, the drag handle, and the mover control. The second group contains common and specific block tools that affect the entire block, followed by inline formatting, and the “More” menu. Optionally “Meta” or “Other” groups can separate some tools in their own segment. A screenshot showing examples of block toolbar segment groupings.

A screenshot showing examples of block toolbar segment groupings.

### The Settings Sidebar should only be used for advanced, tertiary controls The Settings Sidebar is not visible by default on a small / mobile screen, and may also be collapsed in a desktop view. Therefore, it should not be relied on for anything that is necessary for the basic operation of the block. Pick good defaults, make important actions available in the block toolbar, and think of the Settings Sidebar as something that most users should not need to open. In addition, use sections and headers in the Settings Sidebar if there are more than a handful of options, in order to allow users to easily scan and understand the options available. Each Settings Sidebar comes with an “Advanced” section by default. This area houses an “Additional CSS Class” field, and should be used to house other power user controls. ## Setup state vs. live preview state Setup states, sometimes referred to as “placeholders”, can be used to walk users through an initial process before showing the live preview state of the block. The setup process gathers information from the user that is needed to render the block. A block’s setup state is indicated with a grey background to provide clear differentiation for the user. Not all blocks have setup states — for example, the Paragraph block. An example of an image block’s setup state on a grey background

An example of an image block’s setup state on a grey background

A setup state is **not** necessary if: - You can provide good default content in the block that will meet most people’s needs. - That default content is easy to edit and customize. Use a setup state if: - There isn’t a clear default state that would work for most users. - You need to gather input from the user that doesn’t have a 1-1 relationship with the live preview of the block (for example, if you need the user to input an API key to render content). - You need more information from the user in order to render useful default content. For blocks that do have setup states, once the user has gone through the setup process, the placeholder is replaced with the live preview state of that block. An example of the image gallery’s live preview state

An example of the image gallery’s live preview state

When the block is selected, additional controls may be revealed to customize the block’s contents. For example, when the image gallery is selected, it reveals controls to remove or add images. An example of additional controls being revealed on selection of a block.

An example of additional controls being revealed on selection of a block.

In most cases, a block’s setup state is only shown once and then further customization is done via the live preview state. However, in some cases it might be desirable to allow the user to return to the setup state — for example, if all the block content has been deleted or via a link from the block’s toolbar or sidebar. ## Do’s and Don’ts ### Block Toolbar Group toolbar controls in logical segments. Don’t add a segment for each. A screenshot comparing a block toolbar with good vs. bad toolbar segment groupings.

A screenshot comparing a block toolbar with good vs. bad toolbar segment groupings.

### Block identification A block should have a straightforward, short name so users can easily find it in the block library. A block named “YouTube” is easy to find and understand. The same block, named “Embedded Video (YouTube)”, would be less clear and harder to find in the block library. When referring to a block in documentation or UI, use title case for the block title and lowercase for the “block” descriptor. For example: - Paragraph block - Latest Posts block - Media & Text block Blocks should have an identifying icon, ideally using a single color. Try to avoid using the same icon used by an existing block. The core block icons are based on [Material Design Icons](https://fonts.google.com/icons). Look to that icon set, or to [Dashicons](https://developer.wordpress.org/resource/dashicons/) for style inspiration. A screenshot of the block library with concise block names

A screenshot of the block library with concise block names

\ **Do:**\ Use concise block names. A screenshot of the block library with long, multi-line block names

\ **Don’t:**\ Avoid long, multi-line block names. ### Block description Every block should include a description that clearly explains the block’s function. The description will display in the Settings Sidebar. You can add a description by using the description attribute in the [registerBlockType function](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/). Stick to a single imperative sentence with an action + subject format. Examples: - Start with the basic building block of all narrative. - Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content. - Create a bulleted or numbered list. A screenshot of a short block description

A screenshot of a short block description

\ **Do:**\ Use a short, simple block description. A screenshot of a long block description that includes branding

\ **Don’t:**\ Avoid long descriptions and branding. ### Placeholders If your block requires a user to configure some options before you can display it, you should provide an instructive placeholder state.

A screenshot of the Gallery block's placeholder

\ **Do:**\ Provide an instructive placeholder state.

An example Gallery block placeholder but with intense, distracting colors and no instructions

\ **Don’t:**\ Avoid branding and relying on the title alone to convey instructions. ### Selected and unselected states When unselected, your block should preview its content as closely to the front-end output as possible. When selected, your block may surface additional options like input fields or buttons to configure the block directly, especially when they are necessary for basic operation. A Google Maps block with inline, always-accessible controls required for the block to function

A Google Maps block with inline, always-accessible controls required for the block to function

\ **Do:**\ For controls that are essential for the operation of the block, provide them directly inside the block edit view. A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden

A Google Maps block with essential controls moved to the sidebar where they can be contextually hidden

\ **Don’t:**\ Do not put controls that are essential to the block in the sidebar, otherwise the block will appear non-functional to mobile users or desktop users who have dismissed the sidebar. ### Advanced block settings The “Block” tab of the Settings Sidebar can contain additional block options and configuration. Keep in mind that a user can dismiss the sidebar and never use it. You should not put critical options in the Sidebar. A screenshot of the Paragraph block's advanced settings in the sidebar

A screenshot of the Paragraph block's advanced settings in the sidebar

\ **Do:**\ Because the Drop Cap feature is not necessary for the basic operation of the block, you can put it to the Block tab as optional configuration. ### Consider mobile Check how your block looks, feels, and works on as many devices and screen sizes as you can. ### Support Gutenberg’s dark background editor scheme Check how your block looks with [dark backgrounds](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#basic-colors) in the editor. ## Examples To demonstrate some of these practices, here are a few annotated examples of default Gutenberg blocks: ### Paragraph The most basic unit of the editor. The Paragraph block is a simple input field.

#### Placeholder - Simple placeholder text that reads “Type / to choose a block”. The placeholder disappears when the block is selected. #### Selected state - Block Toolbar: Has a switcher to perform transformations to headings, etc. - Block Toolbar: Has basic text alignments - Block Toolbar: Has inline formatting options, bold, italic, strikethrough, and link ### Image Basic image block. Image block placeholder

#### Placeholder - A generic gray placeholder block with options to upload an image, drag and drop an image directly on it, or pick an image from the media library. #### Selected state - Block Toolbar: Alignments, including wide and full-width if the theme supports it. - Block Toolbar: Edit Image, to open the Media Library - Block Toolbar: Link button - When an image is uploaded, a caption input field appears with a “Write caption…” placeholder text below the image:

#### Block settings - Has description: “They’re worth 1,000 words! Insert a single image.” - Has options for changing or adding alt text and adding additional custom CSS classes. *Future improvements to the Image block could include getting rid of the media modal in place of letting users select images directly from the placeholder itself. In general, try to avoid modals.* ### Latest Post Latest Post Block

#### Placeholder Has no placeholder as it works immediately upon insertion. The default inserted state shows the last 5 posts. #### Selected state - Block Toolbar: Alignments - Block Toolbar: Options for picking list view or grid view *Note that the Block Toolbar does not include the Block Chip in this case, since there are no similar blocks to switch to.* #### Block settings - Has description: “Display a list of your most recent posts.” - Has options for post order, narrowing the list by category, changing the default number of posts to show, and showing the post date. *Latest Posts is fully functional as soon as it’s inserted because it comes with good defaults.* # Animation Animation can help reinforce a sense of hierarchy and spatial orientation. This document goes into principles you should follow when you add animation. ## Principles ### Point of Origin - Animation can help anchor an interface element. For example a menu can scale up from the button that opened it. - Animation can help give a sense of place; for example a sidebar can animate in from the side, implying it was always hidden off-screen. - Design your animations as if you’re working with real-world materials. Imagine your user interface elements are made of real materials — when not on screen, where are they? Use animation to help express that. ### Speed - Animations should never block a user interaction. They should be fast, almost always complete in less than 0.2 seconds. - A user should not have to wait for an animation to finish before they can interact. - Animations should be performant. Use `transform` CSS properties when you can, these render elements on the GPU, making them smooth. - If an animation can’t be made fast & performant, leave it out. ### Simple - Don’t bounce if the material isn’t made of rubber. - Don’t rotate, fold, or animate on a curved path. Keep it simple. ### Consistency In creating consistent animations, we have to establish physical rules for how elements behave when animated. When all animations follow these rules, they feel consistent, related, and predictable. An animation should match user expectations, if it doesn’t, it’s probably not the right animation for the job. Reuse animations if one already exists for your task. ## Accessibility Considerations - Animations should be subtle. Be cognizant of users with [vestibular disorders triggered by motion](https://www.ncbi.nlm.nih.gov/pubmed/29017000). - Don’t animate elements that are currently reporting content to adaptive technology (e.g., an `aria-live` region that’s receiving updates). This can cause confusion wherein the technology tries to parse a region that’s actively changing. - Avoid animations that aren’t directly triggered by user behaviors. - Whenever possible, ensure that animations respect the OS-level “Reduce Motion” settings. This can be done by utilizing the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query. In stylesheets, place `animation` and `transition` rules inside `@media not (prefers-reduced-motion)`, or use the `useReducedMotion` hook from `@wordpress/compose` when working with React. - Autoplaying media counts as motion. Don’t start playback for a visitor who prefers reduced motion: use the `useReducedMotion` hook in editor components, or [`prefersReducedMotion()`](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-block-library/src/utils/reduced-motion.js/) in a block view script, which runs outside React. Respecting the preference doesn’t replace a control, so anything that plays for more than a few seconds still needs a visible way to pause or stop it. ## Inventory of Reused Animations The generic `Animate` component is used to animate different parts of the interface. See [the component documentation](https://developer.wordpress.org/block-editor/reference-guide/components/animate/) for more details about the available animations. # Resources ## Figma The [WordPress Design team](https://make.wordpress.org/design/) uses [Figma](https://www.figma.com/) to collaborate and share work. If you’d like to contribute, you can use [the WordPress Figma design library](https://make.wordpress.org/design/handbook/get-involved/tools-figma/) to make mockups. You can also join the [\#design channel](https://app.slack.com/client/T024MFP4J/C02S78ZAL) in [Slack](https://make.wordpress.org/chat/) and if you’d like to ask for advice or otherwise. Figma accounts are free, and with one you can use components from the shared libraries, or duplicate files to your draft if you need to make edits. Full edit access to the WordPress libraries is paid and reserved for the design team. ### How to contribute ### Resources for learning how to use Figma [Getting started with Figma](https://help.figma.com/hc/en-us/categories/360002051613-Get-started) [Top Online Tutorials to Learn Figma for UI/UX Design](https://medium.com/quick-design/top-online-tutorials-to-learn-figma-for-ui-ux-design-4e9c6721a72d) [Take a Tour Around Figma](https://help.figma.com/hc/en-us/articles/15297425105303-Explore-design-files) ### Learning how to use files and projects [Guide to files and projects](https://help.figma.com/hc/en-us/articles/1500005554982-Guide-to-files-and-projects) [Video tutorial](https://www.youtube.com/watch?v=c5HS6smhq2E) ### Learning how to use components [Guide to components in Figma](https://help.figma.com/hc/en-us/articles/360038662654-Guide-to-components-in-Figma) ### Learning how to use WordPress Figma libraries **How to turn on the WordPress Components library in Figma** How to turn on Figma libraries gif

1. Click the **Team Library** icon in the **Assets** Panel: Hovering over the team library icon

1. The **Library** modal will open and allow you to view a list of available libraries. Toggle to *Enable* or *Disable* a specific library: Switching on the WordPress components library in Figma

Switching on the WordPress components library in Figma

**How to refine or contribute to the WordPress components React library *(Coming soon)*** WordPress components in Figma mirror the live React components. Documentation for how to refine or contribute to WordPress components in React is coming soon. If you have questions, please don’t hesitate to ask in the \#design channel on the WordPress community Slack. # Block API Reference Blocks are the fundamental element of the editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor. The following sections will walk you through the existing block APIs: - [Annotations](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-annotations/) - [API Versions](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/) - [Attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) - [Bindings](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-bindings/) - [Context](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/) - [Deprecation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) - [Edit and Save](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) - [Metadata in block.json](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) - [Patterns](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/) - [Registration](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/) - [Selectors](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-selectors/) - [Styles](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) - [Supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) - [Transformations](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-transforms/) - [Templates](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-templates/) - [Variations](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/) # Hooks Reference [Hooks](https://developer.wordpress.org/plugins/hooks/) are a way for one piece of code to interact/modify another piece of code. They provide one way for plugins and themes to interact with the editor, but they’re also used extensively by WordPress Core itself. There are two types of hooks: [Actions](https://developer.wordpress.org/plugins/hooks/actions/) and [Filters](https://developer.wordpress.org/plugins/hooks/filters/). In addition to PHP actions and filters, WordPress also provides a mechanism for registering and executing hooks in JavaScript. This functionality is also available on npm as the [@wordpress/hooks](https://www.npmjs.com/package/@wordpress/hooks) package, for general purpose use. You can also learn more about both APIs: [PHP](https://developer.wordpress.org/reference/) and [JavaScript](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-hooks/). # SlotFills Reference Slot and Fill are components that have been exposed to allow developers to inject items into some predefined places in the Gutenberg admin experience.\ Please see the [SlotFill component docs](https://developer.wordpress.org/block-editor/reference-guide/components/slot-fill/) for more details. In order to use them, we must leverage the [@wordpress/plugins](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-plugins/) api to register a plugin that will inject our items. ## Usage overview In order to access the SlotFills, we need to do four things: 1. Import the `registerPlugin` method from the `@wordpress/plugins` package. 2. Import the SlotFill we want from the `@wordpress/editor'` package. 3. Define a component to render our changes. Our changes/additions will be wrapped in the SlotFill component we imported. 4. Register the plugin. Here is an example using the `PluginPostStatusInfo` slotFill: ``` js import { registerPlugin } from '@wordpress/plugins'; import { PluginPostStatusInfo } from '@wordpress/editor'; const PluginPostStatusInfoTest = () => (

Post Status Info SlotFill

); registerPlugin( 'post-status-info-test', { render: PluginPostStatusInfoTest } ); ``` ## Conditionally rendering SlotFill content With the exception of [MainDashboardButton](https://developer.wordpress.org/block-editor/reference-guides/slotfills/main-dashboard-button/), every available SlotFill is exposed in both the Post Editor and Site Editor and any Fill that is registered will be rendered in both contexts. There are a number of approaches that can be implemented to conditionally render Fills. ### Restricting fills to the Post Editor A fill can be restricted to the Post Editor by checking to see if the current post type object property `viewable` is set to `true`. Any post type not set to `viewable`, does not have an associated edit post screen and is a good indicator that the user is not in the Post Editor. The example below will render its content on the edit post screen for any registered post type. ``` js import { registerPlugin } from '@wordpress/plugins'; import { PluginDocumentSettingPanel, store as editorStore, } from '@wordpress/editor'; import { store as coreStore } from '@wordpress/core-data'; import { useSelect } from '@wordpress/data'; import { __ } from '@wordpress/i18n'; /** * The component to be rendered as part of the plugin. */ const EditPostDocumentSettingPanel = () => { // Retrieve information about the current post type. const isViewable = useSelect( ( select ) => { const postTypeName = select( editorStore ).getCurrentPostType(); const postTypeObject = select( coreStore ).getPostType( postTypeName ); return postTypeObject?.viewable; }, [] ); // If the post type is not viewable, then do not render the plugin. if ( ! isViewable ) { return null; } return (

{ __( 'Only appears in the Edit Post screen' ) }

); }; registerPlugin( 'example-post-edit-only', { render: EditPostDocumentSettingPanel, } ); ``` ### Restricting fills to certain post types. The following example expands on the example above by creating an allow list of post types where the fill should be rendered. In this case, the fill is only rendered when editing pages. ``` js import { registerPlugin } from '@wordpress/plugins'; import { PluginDocumentSettingPanel, store as editorStore, } from '@wordpress/editor'; import { store as coreStore } from '@wordpress/core-data'; import { useSelect } from '@wordpress/data'; import { __, sprintf } from '@wordpress/i18n'; /** * The component to be rendered as part of the plugin. */ const RestrictPostTypes = () => { // Retrieve information about the current post type. const { isViewable, postTypeName } = useSelect( ( select ) => { const postType = select( editorStore ).getCurrentPostType(); const postTypeObject = select( coreStore ).getPostType( postType ); return { isViewable: postTypeObject?.viewable, postTypeName: postType, }; }, [] ); // The list of post types that are allowed to render the plugin. const allowedPostTypes = [ 'page' ]; // If the post type is not viewable or not in the allowed list, do not render the plugin. if ( ! isViewable || ! allowedPostTypes.includes( postTypeName ) ) { return null; } return (

{ sprintf( __( 'Only appears on Post Types that are in the allowed list. %s' ), allowedPostTypes.join( ', ' ) ) }

); }; registerPlugin( 'example-restrict-post-types', { render: RestrictPostTypes, } ); ``` ### Restricting fills to the Side Editor To restrict fills to the Site Editor, the reverse logic is true. If the post type object’s `viewable` property is set to `true`, then the fill should not be rendered. The example below will render its content on any Site Editor screen. ``` js import { registerPlugin } from '@wordpress/plugins'; import { PluginDocumentSettingPanel, store as editorStore, } from '@wordpress/editor'; import { store as coreStore } from '@wordpress/core-data'; import { useSelect } from '@wordpress/data'; import { __ } from '@wordpress/i18n'; /** * The component to be rendered as part of the plugin. */ const SiteEditorDocumentSettingPanel = () => { // Retrieve information about the current post type. const isViewable = useSelect( ( select ) => { const postTypeName = select( editorStore ).getCurrentPostType(); const postTypeObject = select( coreStore ).getPostType( postTypeName ); // A viewable post type is one than can be viewed in the WordPress admin. Internal ones are not set to viewable. return postTypeObject?.viewable; }, [] ); // If the post type is viewable, do not render my fill if ( isViewable ) { return null; } return (

{ __( 'Only appears in the Site Editor' ) }

); }; registerPlugin( 'example-site-editor', { render: SiteEditorDocumentSettingPanel, } ); ``` ### Restricting fills to certain screens in the Site Editor. This example builds on the example above by providing an allow list to control which screens a fill can be rendered within the Site Editor. ``` js import { registerPlugin } from '@wordpress/plugins'; import { PluginDocumentSettingPanel, store as editorStore, } from '@wordpress/editor'; import { store as coreStore } from '@wordpress/core-data'; import { useSelect } from '@wordpress/data'; import { __, sprintf } from '@wordpress/i18n'; /** * The component to be rendered as part of the plugin. */ const SiteEditorDocumentSettingPanel = () => { // Allowed areas in the Site Editor. const allowedSiteEditorScreens = [ 'wp_template', // Templates 'wp_block', // Patterns 'wp_template_part', // Template Parts ]; const { isViewable, postType } = useSelect( ( select ) => { const postTypeName = select( editorStore ).getCurrentPostType(); const postTypeObject = select( coreStore ).getPostType( postTypeName ); return { // A viewable post type is one than can be viewed in the WordPress admin. Internal ones are not set to viewable. isViewable: postTypeObject?.viewable, postType: postTypeName, }; }, [] ); // If the post type is viewable, do not render my plugin. if ( isViewable || ! allowedSiteEditorScreens.includes( postType ) ) { return null; } return (

{ sprintf( __( 'Only appears on Editor Screens that are in the allowed list. %s' ), allowedSiteEditorScreens.join( ', ' ) ) }

); }; registerPlugin( 'example-site-editor-only', { render: SiteEditorDocumentSettingPanel, } ); ``` ## How do they work? SlotFills are created using `createSlotFill`. This creates two components, `Slot` and `Fill` which are then used to create a new component that is exported on the `wp.plugins` global. **Definition of the `PluginPostStatusInfo` SlotFill** ([see core code](https://github.com/WordPress/gutenberg/blob/HEAD/packages/editor/src/components/plugin-post-status-info/index.jsx#L55)) ``` js /** * Defines as extensibility slot for the Summary panel. */ import { createSlotFill, PanelRow } from '@wordpress/components'; export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' ); const PluginPostStatusInfo = ( { children, className } ) => ( { children } ); PluginPostStatusInfo.Slot = Slot; export default PluginPostStatusInfo; ``` This new Slot is then exposed in the editor. The example below is from core and represents the Summary panel. As we can see, the `` is wrapping all of the items that will appear in the panel.\ Any items that have been added via the SlotFill ( see the example above ), will be included in the `fills` parameter and be displayed in the end of the component. See [core code](https://github.com/WordPress/gutenberg/tree/HEAD/packages/editor/src/components/sidebar/post-summary.jsx#L39). ``` js export default function PostSummary( { onActionPerformed } ) { const { isRemovedPostStatusPanel } = useSelect( ( select ) => { // We use isEditorPanelRemoved to hide the panel if it was programmatically removed. We do // not use isEditorPanelEnabled since this panel should not be disabled through the UI. const { isEditorPanelRemoved } = select( editorStore ); return { isRemovedPostStatusPanel: isEditorPanelRemoved( PANEL_NAME ), }; }, [] ); return ( { ( fills ) => ( <> { ! isRemovedPostStatusPanel && ( { fills } ) } ) } ); } ``` ## Currently available SlotFills and examples The following SlotFills are available in the `edit-post` or `editor` packages. Please refer to the individual items below for usage and example details: - [MainDashboardButton](https://developer.wordpress.org/block-editor/reference-guides/slotfills/main-dashboard-button/) - [PluginBlockSettingsMenuItem](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-block-settings-menu-item/) - [PluginDocumentSettingPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-document-setting-panel/) - [PluginMoreMenuItem](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-more-menu-item/) - [PluginPostPublishPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-post-publish-panel/) - [PluginPostStatusInfo](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-post-status-info/) - [PluginPrePublishPanel](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-pre-publish-panel/) - [PluginSidebar](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar/) - [PluginSidebarMoreMenuItem](https://developer.wordpress.org/block-editor/reference-guides/slotfills/plugin-sidebar-more-menu-item/) # RichText Reference RichText is a component that allows developers to render a [`contenteditable` input](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Editable_content), providing users with the option to format block content to make it bold, italics, linked, or use other formatting. The RichText component is extremely powerful because it provides built-in functionality you won’t find in other components: - **Consistent Styling in the Admin and Frontend:** The editable container can be set to any block-level element, such as a `div`, `h2` or `p` tag. This allows the styles you apply in style.css to more easily apply on the frontend and admin, without having to rewrite them in editor.css. - **Cohesive Placeholder Text:** Before the user writes their content, it’s easy to include placeholder text that’s already styled to match the rest of the block editor. - **Control Over Formatting Options:** It’s possible to dictate exactly which formatting options you want to allow for the RichText field. For example, you can dictate whether to allow the user to make text bold, italics or both. Unlike other components that exist in the [Component Reference](https://developer.wordpress.org/block-editor/reference-guide/components/) section, RichText lives separately because it only makes sense within the block editor, and not within other areas of WordPress. ## Property reference For a list of the possible properties to pass your RichText component, [check out the component documentation on GitHub](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md). ## Core blocks using the RichText component There are a number of core blocks using the RichText component. The JavaScript edit function linked below for each block can be used as a best practice reference while creating your own blocks. - **[Button](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/button/edit.jsx):** RichText is used to enter the button’s text. - **[Heading](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/heading/edit.jsx):** RichText is used to enter the heading’s text. - **[Quote](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/quote/edit.jsx):** RichText is used in two places, for both the quotation and citation text. - **[Search](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/search/edit.jsx):** RichText is used in two places, for both the label above the search field and the submit button text. ## Example ``` jsx import { registerBlockType } from '@wordpress/blocks'; import { useBlockProps, RichText } from '@wordpress/block-editor'; registerBlockType( /* ... */, { // ... attributes: { content: { type: 'string', source: 'html', selector: 'h2', }, }, edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return ( setAttributes( { content } ) } // Store updated content as a block attribute placeholder={ __( 'Heading...' ) } // Display this text before any content has been added by the user /> ); }, save( { attributes } ) { const blockProps = useBlockProps.save(); return ; // Saves

Content added in the editor...

to the database for frontend display } } ); ``` ## Common issues and solutions While using the RichText component a number of common issues tend to appear. ### HTML formatting tags display in the content If the HTML tags from text formatting such as `` or `` are being escaped and displayed on the frontend of the site, this is likely due to an issue in your save function. Make sure your code looks something like `` (JSX) within your save function instead of simply outputting the value with `
{ heading }
`. ### Unwanted formatting options still display Before moving forward, consider if using the RichText component makes sense at all. Would it be better to use a basic `input` or `textarea` element? If you don’t think any formatting should be possible, these HTML tags may make more sense. If you’d still like to use RichText, you can eliminate all of the formatting options by specifying the `withoutInteractiveFormatting` property. If you want to limit the formats allowed, you can specify using `allowedFormats` property in your code, see the example above or [the component documentation](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md#allowedformats-array) for details. ### Disable specific format types in Editor The RichText component uses formats to display inline elements, for example images within the paragraph block. If you just want to disable a format from the editor, you can use the `unregisterFormatType` function. For example to disable inline images, use: wp.richText.unregisterFormatType( 'core/image' ); To apply, you would need to enqueue the above script in your plugin or theme. See the JavaScript tutorial for [how to load JavaScript in WordPress](https://developer.wordpress.org/block-editor/how-to-guides/javascript/loading-javascript/). # Component Reference This package includes a library of generic WordPress components to be used for creating common UI elements shared between screens and features of the WordPress dashboard. ## Installation ``` bash npm install @wordpress/components --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.* ## Setup Many components require the package’s CSS stylesheet to be loaded. ### Within WordPress To ensure proper load order, add the `wp-components` stylesheet as a dependency of your plugin’s stylesheet. See [wp_enqueue_style documentation](https://developer.wordpress.org/reference/functions/wp_enqueue_style/#parameters) for how to specify dependencies. ### Outside WordPress Load the stylesheet in your application: ``` js import '@wordpress/components/build-style/style.css'; ``` The RTL version of the stylesheet is available at `@wordpress/components/build-style/style-rtl.css`. ## Usage Within Gutenberg, these components can be accessed by importing from the `components` root directory: ``` jsx import { Button } from '@wordpress/components'; export default function MyButton() { return ; } ``` ### Popovers By default, the `Popover` component will render within an extra element appended to the body of the document. If you want to precisely control where the popovers render, you will need to use the `Popover.Slot` component. The following example illustrates how you can wrap a component using a\ `Popover` and have those popovers render to a single location in the DOM. ``` jsx import { Popover, SlotFillProvider } from '@wordpress/components'; import { MyComponentWithPopover } from './my-component'; const Example = () => { ; }; ``` ### TypeScript This package exposes its own types for the components it exports, however it doesn’t export its own types for component props. If you need to extract the props type, please use `React.ComponentProps` to get the types from the element. ``` import type { ComponentProps } from 'react'; import { Button } from '@wordpress/components'; export default function MyButton( props: ComponentProps< typeof Button > ) { return ; } ``` ## Docs & examples You can browse the components docs and examples at ## 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). This package also has its own [contributing information](https://github.com/WordPress/gutenberg/tree/HEAD/packages/components/CONTRIBUTING.md) where you can find additional details. # Package Reference WordPress exposes a list of JavaScript packages and tools for WordPress development. For information on creating and managing packages in Gutenberg, see the [packages README](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md). For details on the build system and package configuration, see the [@wordpress/build README](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-wp-build/). ## Package Guidelines Packages are the first layer of architecture in Gutenberg. Each package should have a single, clear purpose, include a README, document prerequisites and public APIs, and avoid utility/kitchen-sink patterns. Default to bundled packages unless globals or modules are necessary. For complete guidelines, see the [package guidelines](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#package-guidelines) in the packages README. ## Using the packages via WordPress global JavaScript packages are available as a registered script in WordPress and can be accessed using the `wp` global variable. If you wanted to use the `PlainText` component from the block editor module, first you would specify `wp-block-editor` as a dependency when you enqueue your script: ``` php wp_enqueue_script( 'my-custom-block', plugins_url( $block_path, __FILE__ ), array( 'react', 'wp-blocks', 'wp-block-editor', 'wp-i18n' ) ); ``` After the dependency is declared, you can access the module in your JavaScript code using the global `wp` like so: ``` js const { PlainText } = wp.blockEditor; ``` ## Using the packages via npm All the packages are also available on [npm](https://www.npmjs.com/org/wordpress) if you want to bundle them in your code. Using the same `PlainText` example, you would install the block editor module with npm: ``` bash npm install @wordpress/block-editor --save ``` Once installed, you can access the component in your code using: ``` js import { PlainText } from '@wordpress/block-editor'; ``` ## Testing JavaScript code from a specific major WordPress version There is a way to quickly install a version of the individual WordPress package used with a given WordPress major version using [npm distribution tags](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag) (example for WordPress `5.8.x`): ``` bash npm install @wordpress/block-editor@wp-5.8 ``` It’s also possible to update all existing WordPress packages in the project with a single command: ``` bash npx @wordpress/scripts packages-update --dist-tag=wp-5.8 ``` All major WordPress versions starting from `5.7.x` are supported (e.g., `wp-5.7` or `wp-6.0`). Each individual dist-tag always points to the latest bug fix release for that major version line. # Data Module Reference - [**core**: WordPress Core Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core/) - [**core/annotations**: Annotations](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-annotations/) - [**core/block-directory**: Block directory](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-block-directory/) - [**core/block-editor**: The Block Editor’s Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-block-editor/) - [**core/blocks**: Block Types Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-blocks/) - [**core/commands**: Command Palette](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-commands/) - [**core/customize-widgets**: Customize Widgets](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-customize-widgets/) - [**core/edit-post**: The Editor’s UI Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-edit-post/) - [**core/edit-site**: Edit Site](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-edit-site/) - [**core/edit-widgets**: Edit Widgets](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-edit-widgets/) - [**core/editor**: The Post Editor’s Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-editor/) - [**core/keyboard-shortcuts**: The Keyboard Shortcuts Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-keyboard-shortcuts/) - [**core/notices**: Notices Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-notices/) - [**core/preferences**: Preferences](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-preferences/) - [**core/rich-text**: Rich Text](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-rich-text/) - [**core/viewport**: The Viewport Data](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-viewport/) # Core Blocks Reference This page lists the blocks included in the block-library package. - Items marked with a strikeout (~~strikeout~~) are explicitly disabled. - Blocks marked with **Experimental:** true are only available when Gutenberg is active. - Blocks marked with **Experimental:** fse are only available in the Site Editor. \ **Deprecated blocks** — the following blocks are deprecated and should not be used in new content. - [Comment Author Avatar (deprecated)](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-author-avatar/) (`core/comment-author-avatar`) — Please use the Avatar block instead. - [Author (deprecated)](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-author/) (`core/post-author`) — Please use the Avatar block, the Author Name block, and the Author Biography block instead. - [Comment (deprecated)](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-comment/) (`core/post-comment`) — Please use the Comments block instead. - [Text Columns (deprecated)](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-text-columns/) (`core/text-columns`) — Please use the Columns block instead. ## Accordion Displays a foldable layout that groups content in collapsible sections. - **Name:** [core/accordion](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-accordion/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Allowed Blocks:** core/accordion-item - **Supports:** align (full, wide), anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), contentRole, interactivity, layout, listView, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** autoclose, headingLevel, iconPosition, levelOptions, showIcon ## Accordion Heading Displays a heading that toggles the accordion panel. - **Name:** [core/accordion-heading](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-accordion-heading/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/accordion-item - **Supports:** anchor, background (gradient), color (background, gradients, text), interactivity, shadow, spacing (padding), typography (fontSize, lineHeight), ~~align~~, ~~lock~~, ~~visibility~~ - **Attributes:** iconPosition, level, openByDefault, showIcon, title ## Accordion Item Wraps the heading and panel in one unit. - **Name:** [core/accordion-item](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-accordion-item/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/accordion - **Allowed Blocks:** core/accordion-heading, core/accordion-panel - **Supports:** background (gradient), color (background, button, gradients, heading, link, text), contentRole, interactivity, layout (~~allowEditing~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** openByDefault ## Accordion Panel Contains the hidden or revealed content beneath the heading. - **Name:** [core/accordion-panel](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-accordion-panel/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/accordion-item - **Supports:** allowedBlocks, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), contentRole, interactivity, layout (~~allowEditing~~), shadow, spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~, ~~lock~~, ~~visibility~~ - **Attributes:** templateLock ## Archives Display a date archive of your posts. - **Name:** [core/archives](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-archives/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** displayAsDropdown, showLabel, showPostCounts, type ## Audio Embed a simple audio player. - **Name:** [core/audio](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-audio/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align, anchor, color (link, ~~background~~, ~~text~~), interactivity (clientNavigation), spacing (margin, padding) - **Attributes:** autoplay, blob, caption, id, loop, preload, src ## Avatar Add a user’s avatar. - **Name:** [core/avatar](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-avatar/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align, anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity (clientNavigation), shadow, spacing (margin, padding), ~~alignWide~~, ~~html~~ - **Attributes:** isLink, linkTarget, size, userId ## Pattern Reuse this design across your site. - **Name:** [core/block](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-reusable/core-block-block/) - **Category:** [reusable](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-reusable/) - **Supports:** interactivity (clientNavigation), ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~inserter~~, ~~renaming~~, ~~visibility~~ - **Attributes:** content, ref ## Breadcrumbs Display a breadcrumb trail showing the path to the current page. - **Name:** [core/breadcrumbs](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-breadcrumbs/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** prefersTaxonomy, separator, showCurrentItem, showHomeItem, showOnHomePage ## Button Prompt visitors to take action with a button-style link. - **Name:** [core/button](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-button/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/buttons - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (width), interactivity (clientNavigation), shadow, spacing (padding), splitting, typography (fontSize, lineHeight, textAlign), ~~alignWide~~, ~~align~~, ~~reusable~~ - **Attributes:** backgroundColor, gradient, linkTarget, placeholder, rel, tagName, text, textColor, title, type, url ## Buttons Prompt visitors to take action with a group of button-style links. - **Name:** [core/buttons](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-buttons/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Allowed Blocks:** core/button - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, ~~text~~), contentRole, dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~), listView, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ ## Calendar A calendar of your site’s posts. - **Name:** [core/calendar](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-calendar/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, color (background, link, text), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** month, year ## Terms List Display a list of all terms of a given taxonomy. - **Name:** [core/categories](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-categories/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textColumns), ~~html~~ - **Attributes:** displayAsDropdown, label, showEmpty, showHierarchy, showLabel, showOnlyTopLevel, showPostCounts, taxonomy ## Code Display code snippets that respect your spacing and tabs. - **Name:** [core/code](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-code/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** align (wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight) - **Attributes:** content ## Column A single column within a columns block. - **Name:** [core/column](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-column/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/columns - **Supports:** allowedBlocks, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), interactivity (clientNavigation), layout, shadow, spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** templateLock, verticalAlignment, width ## Columns Display content in multiple columns, with blocks added to each column. - **Name:** [core/columns](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-columns/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Allowed Blocks:** core/column - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (default, ~~allowEditing~~, ~~allowInheriting~~, ~~allowSwitching~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** isStackedOnMobile, templateLock, verticalAlignment ## Comment Author Avatar (deprecated) This block is deprecated. Please use the Avatar block instead. - **Name:** [core/comment-author-avatar](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-author-avatar/) - **Experimental:** fse - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** color (background, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), ~~html~~, ~~inserter~~ - **Attributes:** height, width ## Comment Author Name Displays the name of the author of the comment. - **Name:** [core/comment-author-name](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-author-name/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** isLink, linkTarget ## Comment Content Displays the contents of a comment. - **Name:** [core/comment-content](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-content/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** anchor, background (gradient), color (background, button, gradients, heading, link, text), spacing (padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Comment Date Displays the date on which the comment was posted. - **Name:** [core/comment-date](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-date/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** format, isLink ## Comment Edit Link Displays a link to edit the comment in the WordPress Dashboard. This link is only visible to users with the edit comment capability. - **Name:** [core/comment-edit-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-edit-link/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** anchor, background (gradient), color (background, gradients, link, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** linkTarget ## Comment Reply Link Displays a link to reply to a comment. - **Name:** [core/comment-reply-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comment-reply-link/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comment-template - **Supports:** anchor, background (gradient), color (background, gradients, link, ~~text~~), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Comment Template Contains the block elements used to display a comment, like the title, date, author, avatar and more. - **Name:** [core/comment-template](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-comment-template/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/comments - **Supports:** align, anchor, interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ ## Comments An advanced block that allows displaying post comments using different visual configurations. - **Name:** [core/comments](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** legacy, tagName ## Comments Pagination Displays a paginated navigation to next/previous set of comments, when applicable. - **Name:** [core/comments-pagination](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments-pagination/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/comments - **Allowed Blocks:** core/comments-pagination-previous, core/comments-pagination-numbers, core/comments-pagination-next - **Supports:** align, anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** paginationArrow ## Comments Next Page Displays the next comment’s page link. - **Name:** [core/comments-pagination-next](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments-pagination-next/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/comments-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), spacing (padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** label ## Comments Page Numbers Displays a list of page numbers for comments pagination. - **Name:** [core/comments-pagination-numbers](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments-pagination-numbers/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/comments-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ ## Comments Previous Page Displays the previous comment’s page link. - **Name:** [core/comments-pagination-previous](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments-pagination-previous/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/comments-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), spacing (padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** label ## Comments Title Displays a title with the number of comments. - **Name:** [core/comments-title](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-comments-title/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/comments - **Supports:** align, anchor, background (gradient), color (background, gradients, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** level, levelOptions, showCommentsCount, showPostTitle ## Cover Add an image or video with a text overlay. - **Name:** [core/cover](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-cover/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align, allowedBlocks, anchor, color (button, heading, link, text, ~~background~~, ~~enableContrastChecker~~), dimensions (aspectRatio, minWidth), filter (duotone), interactivity (clientNavigation, interactive), layout (~~allowJustification~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** allowedVideoProviders, alt, backgroundType, contentPosition, customGradient, customOverlayColor, dimRatio, focalPoint, gradient, hasParallax, id, isDark, isRepeated, isUserOverlayColor, minHeight, minHeightUnit, overlayColor, poster, sizeSlug, tagName, templateLock, url, useFeaturedImage ## Details Hide and show additional content. - **Name:** [core/details](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-details/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** align (full, wide), allowedBlocks, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minWidth), interactivity (clientNavigation), layout (~~allowEditing~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** name, placeholder, showContent, summary ## Embed Add a block that displays content pulled from other sites, like Twitter or YouTube. - **Name:** [core/embed](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-embed/core-block-embed/) - **Category:** [embed](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-embed/) - **Supports:** align, anchor, dimensions (minHeight, minWidth), interactivity (clientNavigation), spacing (margin, padding) - **Attributes:** allowResponsive, caption, previewable, providerNameSlug, responsive, type, url ## File Add a link to a downloadable file. - **Name:** [core/file](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-file/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, ~~text~~), dimensions (minHeight, minWidth), interactivity, shadow, spacing (margin, padding), typography (fontSize, lineHeight) - **Attributes:** blob, displayPreview, downloadButtonText, fileId, fileName, href, id, previewHeight, showDownloadButton, textLinkHref, textLinkTarget ## Footnotes Display footnotes added to the page. - **Name:** [core/footnotes](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-footnotes/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~, ~~multiple~~, ~~reusable~~ ## Classic Use the classic WordPress editor. - **Name:** [core/freeform](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-freeform/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~lock~~, ~~renaming~~, ~~reusable~~, ~~visibility~~ - **Attributes:** content ## Gallery Display multiple images in a rich gallery. - **Name:** [core/gallery](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-gallery/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Allowed Blocks:** core/image - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, ~~text~~), dimensions (minHeight, minWidth), filter (duotone), interactivity (clientNavigation), layout (allowEditing, allowSizingOnChildren, default, ~~allowInheriting~~, ~~allowJustification~~, ~~allowOrientation~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~, ~~allowWrap~~), listView, shadow, spacing (blockGap, margin, padding), units (em, px, rem, vh, vw), ~~html~~ - **Attributes:** allowResize, aspectRatio, caption, columns, dynamicContent, fixedHeight, ids, imageCrop, images, linkTarget, linkTo, navigationButtonType, randomOrder, shortCodeTransforms, sizeSlug ## Group Gather blocks in a layout container. - **Name:** [core/group](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-group/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** align (full, wide), allowedBlocks, anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (allowSizingOnChildren), position (sticky), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight, textColumns), ~~html~~ - **Attributes:** tagName, templateLock ## Heading Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content. - **Name:** [core/heading](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-heading/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** \_\_unstablePasteTextInline, align (full, wide), anchor, background (backgroundClip, backgroundImage, backgroundSize, gradient), className, color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), splitting, typography (fitText, fontSize, lineHeight, textAlign, textIndent, textShadow) - **Attributes:** content, level, levelOptions, placeholder ## Home Link Create a link that always points to the homepage of the site. Usually not necessary if there is already a site title link present in the header. - **Name:** [core/home-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-home-link/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/navigation - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** description, label, opensInNewTab ## Custom HTML Add custom HTML code and preview it as you edit. - **Name:** [core/html](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-html/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** interactivity (clientNavigation), listView, ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~visibility~~ - **Attributes:** content ## Icon Insert an SVG icon. - **Name:** [core/icon](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-icon/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align (center, left, right), anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, text), dimensions (minHeight, minWidth, width), interactivity (clientNavigation), shadow, spacing (margin, padding), ~~html~~ - **Attributes:** flipHorizontal, flipVertical, icon, rotation ## Image Insert an image to make a visual statement. - **Name:** [core/image](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-image/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align (center, full, left, right, wide), anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity, shadow, spacing (margin) - **Attributes:** alt, aspectRatio, blob, caption, focalPoint, height, href, id, isDecorative, lightbox, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width ## Latest Comments Display a list of your most recent comments. - **Name:** [core/latest-comments](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-latest-comments/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** commentsToShow, displayAvatar, displayContent, displayDate ## Latest Posts Display a list of your most recent posts. - **Name:** [core/latest-posts](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-latest-posts/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** addLinkToFeaturedImage, categories, displayAuthor, displayFeaturedImage, displayPostContent, displayPostContentRadio, displayPostDate, excerptLength, featuredImageAlign, featuredImageSizeHeight, featuredImageSizeSlug, featuredImageSizeWidth, order, orderBy, postsToShow, selectedAuthor ## List An organized collection of items displayed in a specific order. - **Name:** [core/list](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-list/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Allowed Blocks:** core/list-item - **Supports:** \_\_unstablePasteTextInline, align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), listView, shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** ordered, placeholder, reversed, start, type, values ## List Item An individual item within a list. - **Name:** [core/list-item](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-list-item/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Parent:** core/list - **Allowed Blocks:** core/list - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), interactivity (clientNavigation), shadow, spacing (margin, padding), splitting, typography (fontSize, lineHeight), ~~className~~, ~~html~~ - **Attributes:** content, placeholder ## Login/out Show login & logout links. - **Name:** [core/loginout](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-loginout/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), className, color (background, gradients, link, ~~text~~), contentRole, dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight) - **Attributes:** displayLoginAsForm, redirectToCurrent ## Math Display mathematical notation using LaTeX. - **Name:** [core/math](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-math/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize), ~~html~~ - **Attributes:** latex, mathML ## Media & Text Set media and words side-by-side for a richer layout. - **Name:** [core/media-text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-media-text/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align (full, wide), allowedBlocks, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), filter (duotone), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** align, focalPoint, href, imageFill, isStackedOnMobile, linkClass, linkDestination, linkTarget, mediaAlt, mediaId, mediaLink, mediaPosition, mediaSizeSlug, mediaType, mediaUrl, mediaWidth, rel, useFeaturedImage, verticalAlignment ## Unsupported Your site doesn’t include support for this block. - **Name:** [core/missing](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-missing/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** interactivity (clientNavigation), ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~inserter~~, ~~lock~~, ~~renaming~~, ~~reusable~~, ~~visibility~~ - **Attributes:** originalContent, originalName, originalUndelimitedContent ## More Content before this block is shown in the excerpt on blog and archive pages. Where a theme shows the full content instead, visitors get a “Read more” link to the rest of the post. - **Name:** [core/more](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-more/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** interactivity (clientNavigation), ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~multiple~~, ~~visibility~~ - **Attributes:** customText, noTeaser ## Navigation A collection of blocks that allow visitors to get around your site. - **Name:** [core/navigation](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-navigation/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Allowed Blocks:** core/navigation-link, core/search, core/social-links, core/page-list, core/spacer, core/home-link, core/icon, core/site-title, core/site-logo, core/navigation-submenu, core/loginout, core/buttons - **Supports:** align (full, wide), anchor, ariaLabel, contentRole, inserter, interactivity, layout (allowSizingOnChildren, default, ~~allowInheriting~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), spacing (blockGap, units), typography (fontSize, lineHeight), ~~html~~, ~~renaming~~ - **Attributes:** \_\_unstableLocation, backgroundColor, customBackgroundColor, customOverlayBackgroundColor, customOverlayTextColor, customTextColor, hasIcon, icon, maxNestingLevel, overlay, overlayBackgroundColor, overlayMenu, overlayTextColor, ref, rgbBackgroundColor, rgbTextColor, showSubmenuIcon, submenuVisibility, templateLock, textColor ## Navigation Link Add a page, link, or another item to your navigation. - **Name:** [core/navigation-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-navigation-link/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/navigation - **Allowed Blocks:** core/navigation-link, core/navigation-submenu, core/page-list - **Supports:** anchor, interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~renaming~~, ~~reusable~~ - **Attributes:** description, id, isTopLevelLink, kind, label, opensInNewTab, rel, title, type, url ## Navigation Overlay Close A customizable button to close overlays. - **Name:** [core/navigation-overlay-close](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-navigation-overlay-close/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** color (background, text, ~~gradients~~), dimensions (minHeight, minWidth), shadow, spacing (margin, padding), typography (fontSize, lineHeight) - **Attributes:** displayMode, text ## Submenu Add a submenu to your navigation. - **Name:** [core/navigation-submenu](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-navigation-submenu/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/navigation - **Supports:** anchor, interactivity (clientNavigation), shadow, typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** description, id, isParentSubmenu, isTopLevelItem, kind, label, opensInNewTab, rel, title, type, url ## Page Break Separate your content into a multi-page experience. - **Name:** [core/nextpage](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-nextpage/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/post-content - **Supports:** interactivity (clientNavigation), ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~visibility~~ ## Page List Display a list of all pages. - **Name:** [core/page-list](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-page-list/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Allowed Blocks:** core/page-list-item - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), contentRole, dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** parentPageID ## Page List Item Displays a page inside a list of all pages. - **Name:** [core/page-list-item](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-page-list-item/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Parent:** core/page-list - **Supports:** anchor, contentRole, interactivity (clientNavigation), ~~html~~, ~~inserter~~, ~~lock~~, ~~reusable~~ - **Attributes:** hasChildren, id, label, link, title ## Paragraph Start with the basic building block of all narrative. - **Name:** [core/paragraph](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-paragraph/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** \_\_unstablePasteTextInline, align (full, wide), anchor, background (backgroundClip, backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), splitting, typography (fitText, fontSize, lineHeight, textAlign, textColumns, textIndent, textShadow), ~~className~~ - **Attributes:** content, direction, dropCap, placeholder ## Pattern Placeholder Show a block pattern. - **Name:** [core/pattern](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-pattern/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** interactivity (clientNavigation), ~~html~~, ~~inserter~~, ~~renaming~~, ~~visibility~~ - **Attributes:** slug ## Playlist Embed a simple playlist. - **Name:** [core/playlist](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-playlist/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Allowed Blocks:** core/playlist-track - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity, shadow, spacing (margin, padding), typography (fontSize) - **Attributes:** caption, order, showArtists, showImages, showNumbers, showPlayButtonArtwork, showTrackLength, showTracklist, type, waveformBackgroundColor, waveformBackgroundGradient, waveformColor, waveformGradient, waveformStyle ## Playlist track Playlist track. - **Name:** [core/playlist-track](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-playlist-track/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Parent:** core/playlist - **Supports:** interactivity (clientNavigation), ~~html~~, ~~reusable~~ - **Attributes:** album, artist, blob, id, image, imageAlt, length, src, title, type ## Author (deprecated) This block is deprecated. Please use the Avatar block, the Author Name block, and the Author Biography block instead. - **Name:** [core/post-author](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-author/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, color (background, gradients, link, text), filter (duotone), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~inserter~~ - **Attributes:** avatarSize, byline, isLink, linkTarget, showAvatar, showBio, textAlign ## Author Biography The author biography. - **Name:** [core/post-author-biography](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-author-biography/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign, textColumns, textIndent) ## Author Name The author name. - **Name:** [core/post-author-name](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-author-name/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** isLink, linkTarget ## Comment (deprecated) This block is deprecated. Please use the Comments block instead. - **Name:** [core/post-comment](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-comment/) - **Experimental:** fse - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Allowed Blocks:** core/avatar, core/comment-author-name, core/comment-content, core/comment-date, core/comment-edit-link, core/comment-reply-link - **Supports:** interactivity (clientNavigation), ~~html~~, ~~inserter~~ - **Attributes:** commentId ## Comments Count Display a post’s comments count. - **Name:** [core/post-comments-count](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-comments-count/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (gradient), color (background, gradients, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Comments Form Display a post’s comments form. - **Name:** [core/post-comments-form](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-comments-form/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Comments Link Displays the link to the current post comments. - **Name:** [core/post-comments-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-comments-link/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, color (background, link, ~~text~~), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Content Displays the contents of a post or page. - **Name:** [core/post-content](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-content/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** tagName ## Date Display a custom date. - **Name:** [core/post-date](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-date/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** datetime, format, isLink ## Excerpt Display the excerpt. - **Name:** [core/post-excerpt](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-excerpt/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign, textColumns), ~~html~~ - **Attributes:** excerptLength, moreText, showMoreOnNewLine ## Featured Image Display a post’s featured image. - **Name:** [core/post-featured-image](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-featured-image/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (center, full, left, right, wide), anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity (clientNavigation), shadow, spacing (margin, padding), ~~html~~ - **Attributes:** aspectRatio, customGradient, customOverlayColor, dimRatio, gradient, height, isLink, linkTarget, overlayColor, rel, scale, sizeSlug, useFirstImageFromPost, width ## Post Navigation Link Displays the next or previous post link that is adjacent to the current post. - **Name:** [core/post-navigation-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-navigation-link/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~, ~~reusable~~ - **Attributes:** arrow, label, linkLabel, showTitle, taxonomy, type ## Post Template Contains the block elements used to render a post, like the title, date, featured image, content or excerpt, and more. - **Name:** [core/post-template](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-template/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/query - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ ## Post Terms Post terms. - **Name:** [core/post-terms](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-terms/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** prefix, separator, suffix, term ## Time to Read Show minutes required to finish reading the post. Can also show a word count. - **Name:** [core/post-time-to-read](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-time-to-read/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** averageReadingSpeed, displayAsRange, displayMode ## Title Displays the title of a post, page, or any other content-type. - **Name:** [core/post-title](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-post-title/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fitText, fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** isLink, level, levelOptions, linkTarget, placeholder, rel ## Preformatted Add text that respects your spacing and tabs, and also allows styling. - **Name:** [core/preformatted](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-preformatted/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight) - **Attributes:** content ## Pullquote Give special visual emphasis to a quote from your text. - **Name:** [core/pullquote](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-pullquote/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** align (full, left, right, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign, textIndent) - **Attributes:** citation, value ## Query Loop An advanced block that allows displaying post types based on different query parameters and visual configurations. - **Name:** [core/query](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, interactivity, layout, spacing (blockGap), ~~html~~ - **Attributes:** enhancedPagination, namespace, query, queryId, tagName ## No Results Contains the block elements used to render content when no query results are found. - **Name:** [core/query-no-results](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-no-results/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/query - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ ## Pagination Displays a paginated navigation to next/previous set of posts, when applicable. - **Name:** [core/query-pagination](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-pagination/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/query - **Allowed Blocks:** core/query-pagination-previous, core/query-pagination-numbers, core/query-pagination-next - **Supports:** align, anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~), spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** paginationArrow, showLabel ## Next Page Displays the next posts page link. - **Name:** [core/query-pagination-next](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-pagination-next/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/query-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** label ## Page Numbers Displays a list of page numbers for pagination. - **Name:** [core/query-pagination-numbers](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-pagination-numbers/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/query-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), spacing (padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** midSize ## Previous Page Displays the previous posts page link. - **Name:** [core/query-pagination-previous](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-pagination-previous/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Parent:** core/query-pagination - **Supports:** anchor, background (gradient), color (background, gradients, ~~text~~), interactivity (clientNavigation), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ - **Attributes:** label ## Query Title Display the query title. - **Name:** [core/query-title](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-title/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (gradient), color (background, gradients, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** level, levelOptions, showPrefix, showSearchTerm, type ## Query Total Display the total number of results in a query. - **Name:** [core/query-total](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-query-total/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/query - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** displayType ## Quote Give quoted text visual emphasis. “In quoting others, we cite ourselves.” — Julio Cortázar - **Name:** [core/quote](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-quote/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** align (full, left, right, wide), allowedBlocks, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout (~~allowEditing~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** citation, textAlign, value ## Read More Displays the link of a post, page, or any other content-type. - **Name:** [core/read-more](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-read-more/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** content, linkTarget ## RSS Display entries from any RSS or Atom feed. - **Name:** [core/rss](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-rss/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), ~~html~~ - **Attributes:** blockLayout, columns, displayAuthor, displayDate, displayExcerpt, excerptLength, feedURL, itemsToShow, openInNewTab, rel ## Search Help visitors find your content. - **Name:** [core/search](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-search/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align (center, left, right), anchor, background (gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity, shadow, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** buttonPosition, buttonText, buttonUseIcon, label, placeholder, query, showLabel, tagName, width, widthUnit ## Separator Create a break between ideas or sections with a horizontal separator. - **Name:** [core/separator](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-separator/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** align (center, full, wide), anchor, color (background, gradients, ~~enableContrastChecker~~, ~~text~~), interactivity (clientNavigation), spacing (margin) - **Attributes:** opacity, tagName ## Shortcode Insert additional custom elements with a WordPress shortcode. - **Name:** [core/shortcode](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-shortcode/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** ~~className~~, ~~customCSS~~, ~~customClassName~~, ~~html~~, ~~visibility~~ - **Attributes:** text ## Site Logo Display an image to represent this site. Update this block and the changes apply everywhere. - **Name:** [core/site-logo](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-site-logo/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align, anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity (clientNavigation), spacing (margin, padding), ~~alignWide~~, ~~html~~ - **Attributes:** isLink, linkTarget, shouldSyncIcon, width ## Site Tagline Describe in a few words what this site is about. This is important for search results, sharing on social media, and gives overall clarity to visitors. - **Name:** [core/site-tagline](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-site-tagline/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), contentRole, dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fitText, fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** level, levelOptions ## Site Title Displays the name of this site. Update the block, and the changes apply everywhere it’s used. This will also appear in the browser title bar and in search results. - **Name:** [core/site-title](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-site-title/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fitText, fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** isLink, level, levelOptions, linkTarget ## Social Icon Display an icon linking to a social profile or site. - **Name:** [core/social-link](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-social-link/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Parent:** core/social-links - **Supports:** anchor, interactivity (clientNavigation), ~~html~~, ~~reusable~~ - **Attributes:** label, rel, service, url ## Social Icons Display icons linking to your social profiles or sites. - **Name:** [core/social-links](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-social-links/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Allowed Blocks:** core/social-link - **Supports:** align (center, left, right), anchor, background (gradient), color (background, gradients, ~~enableContrastChecker~~, ~~text~~), contentRole, interactivity (clientNavigation), layout (default, ~~allowInheriting~~, ~~allowSwitching~~, ~~allowVerticalAlignment~~), listView, shadow, spacing (blockGap, margin, padding, units), ~~html~~ - **Attributes:** customIconBackgroundColor, customIconColor, iconBackgroundColor, iconBackgroundColorValue, iconColor, iconColorValue, openInNewTab, showLabels, size ## Spacer Add white space between blocks and customize its height. - **Name:** [core/spacer](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-spacer/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** anchor, interactivity (clientNavigation), spacing (margin) - **Attributes:** height, width ## Tab List Display the tab buttons for a tabbed interface. - **Name:** [core/tab-list](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-tab-list/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/tabs - **Supports:** ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, text), layout (default, ~~allowOrientation~~, ~~allowVerticalAlignment~~, ~~allowWrap~~), shadow, spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~, ~~lock~~, ~~visibility~~ - **Attributes:** tabs ## Tab Panel Content for a tab in a tabbed interface. - **Name:** [core/tab-panel](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-tab-panel/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/tab-panels - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, heading, link, text), layout, shadow, spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~, ~~visibility~~ - **Attributes:** label ## Tab Panels Container for tab panel content in a tabbed interface. - **Name:** [core/tab-panels](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-tab-panels/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Parent:** core/tabs - **Allowed Blocks:** core/tab-panel - **Supports:** background (backgroundImage, backgroundSize, gradient), color (background, button, heading, link, text), dimensions (minHeight), shadow, spacing (padding), typography (fontSize, lineHeight), ~~html~~, ~~lock~~, ~~visibility~~ ## Table Create structured content in rows and columns to display information. - **Name:** [core/table](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-table/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** align, anchor, background (gradient), color (background, gradients, link, text), interactivity (clientNavigation), spacing (margin, padding), typography (fontSize, lineHeight, textAlign) - **Attributes:** body, caption, foot, hasFixedLayout, head ## Table of Contents Summarize your post with a list of headings. Add HTML anchors to Heading blocks to link them here. - **Name:** [core/table-of-contents](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-table-of-contents/) - **Experimental:** true - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** anchor, ariaLabel, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** maxLevel, onlyIncludeCurrentPage, ordered ## Tabs Display content in a tabbed interface to help users navigate detailed content with ease. - **Name:** [core/tabs](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-tabs/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Allowed Blocks:** core/tab-list, core/tab-panels - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, heading, link, text), dimensions (minWidth), interactivity, layout (~~allowEditing~~), shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~ - **Attributes:** activeTabIndex, editorActiveTabIndex ## Tag Cloud A cloud of popular keywords, each sized by how often it appears. - **Name:** [core/tag-cloud](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/core-block-tag-cloud/) - **Category:** [widgets](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-widgets/) - **Supports:** align, anchor, background (backgroundImage, backgroundSize, gradient), color (background, link, ~~text~~), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (lineHeight), ~~html~~ - **Attributes:** largestFontSize, numberOfTags, showTagCounts, smallestFontSize, taxonomy ## Template Part Edit the different global regions of your site, like the header, footer, sidebar, or create your own. - **Name:** [core/template-part](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-template-part/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align, interactivity (clientNavigation), ~~html~~, ~~renaming~~, ~~reusable~~ - **Attributes:** area, slug, tagName, theme ## Term Count Displays the post count of a taxonomy term. - **Name:** [core/term-count](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-term-count/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** bracketType ## Term Description Display the description of categories, tags and custom taxonomies when viewing an archive. - **Name:** [core/term-description](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-term-description/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ ## Term Name Displays the name of a taxonomy term. - **Name:** [core/term-name](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-term-name/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fontSize, lineHeight, textAlign), ~~html~~ - **Attributes:** isLink, level, levelOptions ## Term Template Contains the block elements used to render a taxonomy term, like the name, description, and more. - **Name:** [core/term-template](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-term-template/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Ancestor:** core/terms-query - **Supports:** align (full, wide), anchor, background (backgroundImage, backgroundSize, gradient), color (background, button, gradients, heading, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), layout, shadow, spacing (blockGap, margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ ## Terms Query An advanced block that allows displaying taxonomy terms based on different query parameters and visual configurations. - **Name:** [core/terms-query](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/core-block-terms-query/) - **Category:** [theme](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-theme/) - **Supports:** align (full, wide), anchor, interactivity, layout, spacing (blockGap, margin, padding), ~~html~~ - **Attributes:** tagName, termQuery ## Text Columns (deprecated) This block is deprecated. Please use the Columns block instead. - **Name:** [core/text-columns](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/core-block-text-columns/) - **Category:** [design](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-design/) - **Supports:** interactivity (clientNavigation), ~~inserter~~ - **Attributes:** columns, content, width ## Poetry Insert poetry. Use special spacing formats. Or quote song lyrics. - **Name:** [core/verse](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/core-block-verse/) - **Category:** [text](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-text/) - **Supports:** anchor, background (backgroundImage, backgroundSize, gradient), color (background, gradients, link, text), dimensions (minHeight, minWidth), interactivity (clientNavigation), shadow, spacing (margin, padding), typography (fitText, fontSize, lineHeight, textAlign, textColumns, textIndent) - **Attributes:** content ## Video Embed a video from your media library or upload a new one. - **Name:** [core/video](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/core-block-video/) - **Category:** [media](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/core-blocks-media/) - **Supports:** align, anchor, dimensions (minHeight, minWidth), filter (duotone), interactivity (clientNavigation, interactive), shadow, spacing (margin, padding) - **Attributes:** autoplay, blob, caption, controls, height, id, loop, muted, playsInline, poster, preload, src, tracks, width # Theme.json Reference This reference guide lists the settings and style properties defined in the theme.json schema. See the [theme.json how to guide](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/) for examples and guide on how to use the theme.json file in your theme. - [Version 3 (latest)](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/) ## Older versions - [Migrating to Newer Theme.json Versions](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/) - [Version 1](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-v1/) - [Version 2](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-v2/) # Interactivity API Reference The Interactivity API, [introduced in WordPress 6.5](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/), provides a standard way for developers to add interactions to the front end of their blocks. The API is also used in many Core WordPress blocks, including Search, Query, Navigation, and File. This standard makes it easier for developers to create rich, interactive user experiences, from simple counters or pop-ups to more complex features like instant page navigation, instant search, shopping carts, or checkouts. Blocks can share data, actions, and callbacks between them. This makes communication between blocks simpler and less error-prone. For example, clicking on an “add to cart” block can seamlessly update a separate “cart” block. For more information about the genesis of the Interactivity API, check out the [original proposal](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/). You can also review the [merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/), the [status update post](https://make.wordpress.org/core/2023/08/15/status-update-on-the-interactivity-api/), and the official [Trac ticket](https://core.trac.wordpress.org/ticket/60356).
The Interactivity API is supported by the package [`@wordpress/interactivity`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/) which is bundled in WordPress Core from v6.5
## Navigating the Interactivity API docs Use the following links to locate the topic you’re interested in. If you have never worked with the Interactivity API before, consider reading through the following resources in the order listed. - **[Requirements](#requirements-of-the-interactivity-api):** Check this section before you start creating your interactive blocks with the Interactivity API. - **[Quick Start Guide](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-quick-start-guide/):** Get a custom block using the Interactivity API up and running in less than one minute. - **[Tutorial: A first look at the Interactivity API](https://developer.wordpress.org/news/2024/04/11/a-first-look-at-the-interactivity-api/):** This article from the [WordPress Developer Blog](https://developer.wordpress.org/news/) is a great way to get introduced to the Interactivity API. - **[Core Concepts](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/):** Gain a better understanding of concepts and mental models related to Interactivity API development from this section. - **[Directives and Store](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/directives-and-store/):** To take a deep dive into how the API works internally, the list of Directives, and how the Store works. - **[Docs and Examples](#docs-examples):** Additional resources to learn/read more about the Interactivity API. To get a deeper understanding of what the Interactivity API is or find answers to questions you may have about this standard, check the following resources: - **[About the Interactivity API](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-about/):** To learn more about the API Goals and the reasoning behind the use of a standard to add interactivity to blocks. - **[Frequently Asked Questions](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/iapi-faq/):** To find responses to some frequently asked questions about the technology behind and alternatives. ## Requirements of the Interactivity API Interactivity API is included in Core in WordPress 6.5. For versions below, you’ll need Gutenberg 17.5 or higher installed and activated in your WordPress installation. It’s also important to highlight that the block creation workflow doesn’t change, and all the [prerequisites](https://developer.wordpress.org/block-editor/getting-started/devenv/) remain the same. These include: - [Code Editor](https://developer.wordpress.org/block-editor/getting-started/devenv/#code-editor) - [Node.js development tools](https://developer.wordpress.org/block-editor/getting-started/devenv/#node-js-development-tools) - [Local WordPress environment (site)](https://developer.wordpress.org/block-editor/getting-started/devenv/#local-wordpress-environment) You can start creating interactions once you set up a block development environment and run WordPress 6.5+ (or Gutenberg 17.5+). ### Code requirements #### Add `interactivity` to your project Install the Interactivity API to your project with the following command: ``` bash npm install @wordpress/interactivity --save ``` Import the store into your `view.js`. Refer to the [store documentation](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/directives-and-store/#the-store) for more information. ``` js import { store } from '@wordpress/interactivity'; ``` #### Add `interactivity` support to `block.json` To indicate that the block [supports](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) the Interactivity API features, add `"interactivity": true` to the `supports` attribute of the block’s `block.json` file. In `block.json`: ``` json "supports": { "interactivity": true }, ``` Refer to the [`interactivity` support property docs](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#interactivity) to get a more detailed description of this property. #### Load Interactivity API JavaScript code with `viewScriptModule` The Interactivity API provides the `@wordpress/interactivity` Script Module. JavaScript using the Interactivity API should be implemented as Script Modules so they can depend on `@wordpress/interactivity`. [Script Modules have been available since WordPress 6.5](https://make.wordpress.org/core/2024/03/04/script-modules-in-6-5/). Blocks can use [`viewScriptModule` block metadata](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#view-script-module) to enqueue their Script Modules easily: In `block.json`: ``` json { "viewScriptModule": "file:./view.js" } ``` The use of `viewScriptModule` also requires the `--experimental-modules` flag for both the [`build`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#build) and [`start`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/#start) scripts of `wp-scripts` to ensure a proper build of the Script Modules. > **Note:** If you scaffolded your block using the [`@wordpress/create-block-interactive-template`](https://www.npmjs.com/package/@wordpress/create-block-interactive-template), this flag is already included in your `package.json` scripts and no manual configuration is needed. If you need to add it manually, update your `package.json`: ``` json { "scripts": { "build": "wp-scripts build --experimental-modules", "start": "wp-scripts start --experimental-modules" } } ``` #### Add `wp-interactive` directive to a DOM element To “activate” the Interactivity API in a DOM element (and its children), add the [`wp-interactive`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-interactivity/packages-interactivity-api-reference/#wp-interactive) directive to the DOM element in the block’s `render.php` or `save.js` files. ``` html

``` Refer to the [`wp-interactive` documentation](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/directives-and-store/#wp-interactive) for a more detailed description of this directive. ## Docs & Examples Here you have some more resources to learn/read more about the Interactivity API: - [WordPress 6.5 Dev Note](https://make.wordpress.org/core/2024/03/04/interactivity-api-dev-note/) - [Merge announcement](https://make.wordpress.org/core/2024/02/19/merge-announcement-interactivity-api/) - [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) - [Interactivity API Discussions](https://github.com/WordPress/gutenberg/discussions/52882), especially the [showcase](https://github.com/WordPress/gutenberg/discussions/55642#discussioncomment-9667164) discussions. - [wpmovies.dev](https://wpmovies.dev/) demo and its [wp-movies-demo](https://github.com/WordPress/wp-movies-demo) repo - Examples using the Interactivity API at [block-development-examples](https://github.com/WordPress/block-development-examples): - [`my-first-interactive-block`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/my-first-interactive-block) - [`interactivity-api-countdown-3cd73e`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-countdown-3cd73e) - [`interactivity-api-quiz-1835fa`](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/interactivity-api-quiz-1835fa)
There’s a Tracking Issue opened to ease the coordination of the work related to the Interactivity API Docs: [Documentation for the Interactivity API – Tracking Issue \#53296](https://github.com/WordPress/gutenberg/issues/53296)
# View Configuration Reference DataViews-powered admin screens (such as the Site Editor’s Pages, Templates, Template Parts, and Patterns screens) load their configuration from the server: what layout the screen uses by default, which fields are visible, the preconfigured views offered in the sidebar, and the fields of the Quick Edit form. The configuration is built per entity — identified by its kind (e.g. `postType`) and name (e.g. `page`) — and can be customized through the dynamic `get_entity_view_config_{$kind}_{$name}` filter, where the dynamic portions are lowercased: the `postType`/`page` entity maps to the `get_entity_view_config_posttype_page` filter. The editor retrieves the result through the `/wp/v2/view-config?kind={kind}&name={name}` REST API endpoint. Related docs: - [Server-side view configuration filter](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/filters-and-hooks/#server-side-view-configuration-filter): how to customize the configuration via the `get_entity_view_config_{$kind}_{$name}` filter and its methods (`merge`, `remove`, `replace`, `set`). - [@wordpress/dataviews](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-dataviews/) package. - Storybook: - [DataViews](https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviews--docs) - [DataViewsPicker](https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviewspicker--docs) - [DataForm](https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataform--docs) - [Field types](https://wordpress.github.io/gutenberg/?path=/docs/dataviews-fieldtypes--docs) This section lists the properties of the view configuration. It has four top-level keys: - [`default_view`](#default_view): the view applied when the user has not made any changes. - [`default_layouts`](#default_layouts): the layout types available to the user, and the view overrides each one applies. - [`view_list`](#view_list): the preconfigured views displayed in the screen’s sidebar. - [`form`](#form): the fields of the Quick Edit form. ## default_view > The view object is the same structure the [DataViews component](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-dataviews/#view-object) consumes; see its documentation for the complete list of view properties and filter operators. There are two properties from the DataViews API that cannot be configured via the server filter: `search` and `page`. These are URL-managed that are set by the editor when the user searches or paginates. The default DataViews configuration for the screen: layout type, visible fields, sorting, filtering, and pagination. It is the view users see before they customize anything. | Property | Description | Type | |----|----|----| | type | The layout type, one of `table`, `grid`, `list`, or `activity`. | `string` | | fields | Ids of the fields that are visible, in display order. | `[ string ]` | | titleField | Id of the field used as the record title. | `string` | | mediaField | Id of the field used as the record media (e.g. featured image or preview). | `string` | | descriptionField | Id of the field used as the record description. | `string` | | showTitle | Whether the title is shown. Defaults to `true`. | `boolean` | | showMedia | Whether the media is shown. Defaults to `true`. | `boolean` | | showDescription | Whether the description is shown. Defaults to `true`. | `boolean` | | showLevels | Whether to display hierarchical levels for the records (e.g. child pages indented under their parent). Defaults to `false`. | `boolean` | | sort | The default sort: the field id and the direction (`asc` or `desc`). | `{ field, direction }` | | filters | Filters applied to the dataset. A filter with `isLocked` set cannot be removed by the user. | `[ { field, operator, value, isLocked } ]` | | perPage | Number of records per page. | `integer` | | layout | Configuration specific to the selected layout type. See [`default_layouts`](#default_layouts). | `object` | ## default_layouts The layout types the user can switch between. Each key is a layout type (`table`, `grid`, `list`, `activity`); a type that is not present is not offered in the UI. Each value is a partial view configuration applied when the user switches to that layout type — an empty array means the type is available with no overrides. | Property | Description | Type | |----|----|----| | table | View overrides applied when the table layout is selected. | `object` | | grid | View overrides applied when the grid layout is selected. | `object` | | list | View overrides applied when the list layout is selected. | `object` | Common overrides are `layout` (layout-specific configuration, such as per-field column `styles` for tables or `badgeFields` for grids) and view properties like `showMedia`. Table column `styles` are keyed by field id and apply to the columns listed in `fields`; the primary column (the one rendering `titleField`, `mediaField`, and `descriptionField`) takes the width the other columns leave over, so styles keyed by those field ids are ignored. When the view has no primary column, the last column in `fields` takes the leftover width instead: ``` php $default_layouts = array( 'table' => array( 'showMedia' => false, 'layout' => array( 'styles' => array( 'author' => array( 'width' => '1%' ), ), ), ), 'grid' => array( 'showMedia' => true, 'layout' => array( 'badgeFields' => array( 'sync-status' ), ), ), ); ``` ## view_list The preconfigured views displayed in the screen’s sidebar (e.g. “All pages”, “Published”, “Drafts”). Each entry is: | Property | Description | Type | |----|----|----| | title | Title of the view, displayed in the sidebar. | `string` | | slug | Unique identifier for the view. Used as the member identity when merging patches. | `string` | | view | Partial view configuration applied on top of `default_view` when the view is selected — typically locked `filters`, but any view property works. Optional. | `object` | ``` php $view_list = array( array( 'title' => __( 'All pages' ), 'slug' => 'all', ), array( 'title' => __( 'Drafts' ), 'slug' => 'drafts', 'view' => array( 'filters' => array( array( 'field' => 'status', 'operator' => 'isAny', 'value' => 'draft', 'isLocked' => true, ), ), ), ), ); ``` ## form > The form structure is shared with the [DataForm component](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-dataviews/#form-object); see its documentation for the complete Form Field API, including the additional options of each layout type. The DataForm configuration for the Quick Edit form: which fields are displayed, in which order, and how each one is laid out. | Property | Description | Type | |----|----|----| | layout | The default layout for the form fields, e.g. `{ 'type' => 'panel' }`. | `{ type }` | | fields | The fields of the form, in display order. Each entry is a field id, or an object for further configuration (see below). | `[ string \| object ]` | A field declared as an object accepts: | Property | Description | Type | |----|----|----| | id | Id of the field. Used as the member identity when merging patches. | `string` | | label | Label displayed for the field, overriding the field’s own. | `string` | | layout | How the field is rendered: `type` is one of `regular`, `panel`, `card`, or `row`, and `labelPosition` is one of `side`, `top`, or `none`. | `{ type, labelPosition }` | | children | Fields combined under this entry, following the same shape as `fields`. | `[ string \| object ]` | Only registered fields are rendered: a form entry whose field is not registered for the entity is dropped by the editor. ``` php $form = array( 'layout' => array( 'type' => 'panel' ), 'fields' => array( array( 'id' => 'featured_media', 'layout' => array( 'type' => 'regular', 'labelPosition' => 'none', ), ), array( 'id' => 'status', 'label' => __( 'Status' ), 'children' => array( 'status', 'password', 'sticky' ), ), 'date', 'author', ), ); ``` # Edit and Save When registering a block with JavaScript on the client, the `edit` and `save` functions provide the interface for how a block is going to be rendered within the editor, how it will operate and be manipulated, and how it will be saved. ## Edit The `edit` function describes the structure of your block in the context of the editor. This represents what the editor will render when the block is used. ``` jsx import { useBlockProps } from '@wordpress/block-editor'; // ... const blockSettings = { apiVersion: 3, // ... edit: () => { const blockProps = useBlockProps(); return
Your block.
; }, }; ``` ### Block wrapper props The first thing to notice here is the use of the `useBlockProps` React hook on the block wrapper element. In the example above, the block wrapper renders a “div” in the editor, but in order for the Gutenberg editor to know how to manipulate the block, add any extra classNames that are needed for the block… the block wrapper element should apply props retrieved from the `useBlockProps` react hook call. The block wrapper element should be a native DOM element, like `
` and ``, or a React component that forwards any additional props to native DOM elements. Using a `` or `` component, for instance, would be invalid. If the element wrapper needs any extra custom HTML attributes, these need to be passed as an argument to the `useBlockProps` hook. For example to add a `my-random-classname` className to the wrapper, you can use the following code: ``` jsx import { useBlockProps } from '@wordpress/block-editor'; // ... const blockSettings = { apiVersion: 3, // ... edit: () => { const blockProps = useBlockProps( { className: 'my-random-classname', } ); return
Your block.
; }, }; ``` ### attributes The `edit` function also receives a number of properties through an object argument. You can use these properties to adapt the behavior of your block. The `attributes` property surfaces all the available attributes and their corresponding values, as described by the `attributes` property when the block type was registered. See [attributes documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) for how to specify attribute sources. In this case, assuming we had defined an attribute of `content` during block registration, we would receive and use that value in our edit function: ``` js edit: ( { attributes } ) => { const blockProps = useBlockProps(); return
{ attributes.content }
; }; ``` The value of `attributes.content` will be displayed inside the `div` when inserting the block in the editor. ### isSelected The isSelected property is a boolean that communicates whether the block is currently selected. ``` jsx edit: ( { attributes, isSelected } ) => { const blockProps = useBlockProps(); return (
Your block. { isSelected && ( Shows only when the block is selected. ) }
); }; ``` ### setAttributes This function allows the block to update individual attributes based on user interactions. ``` jsx edit: ( { attributes, setAttributes, isSelected } ) => { const blockProps = useBlockProps(); // Simplify access to attributes const { content, mySetting } = attributes; // Toggle a setting when the user clicks the button const toggleSetting = () => setAttributes( { mySetting: ! mySetting } ); return (
{ content } { isSelected && ( ) }
); }; ``` When using attributes that are objects or arrays it’s a good idea to copy or clone the attribute prior to updating it: ``` js // Good - a new array is created from the old list attribute and a new list item: const { list } = attributes; const addListItem = ( newListItem ) => setAttributes( { list: [ ...list, newListItem ] } ); // Bad - the list from the existing attribute is modified directly to add the new list item: const { list } = attributes; const addListItem = ( newListItem ) => { list.push( newListItem ); setAttributes( { list } ); }; ``` Why do this? In JavaScript, arrays and objects are passed by reference, so this practice ensures changes won’t affect other code that might hold references to the same data. Furthermore, the Gutenberg project follows the philosophy of the Redux library that [state should be immutable](https://redux.js.org/faq/immutable-data#what-are-the-benefits-of-immutability)—data should not be changed directly, but instead a new version of the data created containing the changes. The `setAttributes` also supports an updater function as an argument. It must be a pure function, which takes current attributes as its only argument and returns updated attributes. This method is helpful when you want to update a value based on a previous state or when working with objects and arrays. ***Note:** Since WordPress 6.9.* ``` js // Toggle a setting when the user clicks the button. const toggleSetting = () => setAttributes( ( currentAttr ) => ( { mySetting: ! currentAttr.mySetting, } ) ); // Add item to the list. const addListItem = ( newListItem ) => setAttributes( ( currentAttr ) => ( { list: [ ...currentAttr.list, newListItem ], } ) ); ``` ## Save The `save` function defines the way in which the different attributes should be combined into the final markup, which is then serialized into `post_content`. ``` jsx save: () => { const blockProps = useBlockProps.save(); return
Your block.
; }; ``` For most blocks, the return value of `save` should be an [instance of WordPress Element](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-element/) representing how the block is to appear on the front of the site. *Note:* While it is possible to return a string value from `save`, it *will be escaped*. If the string includes HTML markup, the markup will be shown on the front of the site verbatim, not as the equivalent HTML node content. If you must return raw HTML from `save`, use `wp.element.RawHTML`. As the name implies, this is prone to [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) and therefore is discouraged in favor of a WordPress Element hierarchy whenever possible. *Note:* The save function should be a pure and stateless function that depends only on the attributes used to invoke it. It shouldn’t use any APIs such as `useState` or `useEffect`, nor retrieve information from another source; for example, it is not possible to use the data module inside – `select( store ).selector( ... )`.\ This is because if the external information changes, the block may be flagged as invalid when the post is later edited ([read more about Validation](#validation)). If there is a need to have other information as part of the save, developers can consider one of these two alternatives: - Use [dynamic blocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/) and dynamically retrieve the required information on the server. - Store the external value as an attribute which is dynamically updated in the block’s `edit` function as changes occur. For [dynamic blocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/), the return value of `save` could represent a cached copy of the block’s content to be shown only in case the plugin implementing the block is ever disabled. If left unspecified, the default implementation will save no markup in post content for the dynamic block, instead deferring this to always be calculated when the block is shown on the front of the site. ### block wrapper props Like the `edit` function, when rendering static blocks, it’s important to add the block props returned by `useBlockProps.save()` to the wrapper element of your block. This ensures that the block class name is rendered properly in addition to any HTML attribute injected by the block supports API. ### attributes As with `edit`, the `save` function also receives an object argument including attributes which can be inserted into the markup. ``` jsx save: ( { attributes } ) => { const blockProps = useBlockProps.save(); return
{ attributes.content }
; }; ``` When saving your block, you want to save the attributes in the same format specified by the attribute source definition. If no attribute source is specified, the attribute will be saved to the block’s comment delimiter. See the [Block Attributes documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) for more details. ### innerBlocks There is a second property in the props passed to the `save` function, `innerBlocks`. This property is typically used for internal operations, and there are very few scenarios where you would need to use it. `innerBlocks`, when initialized, is an array containing object representations of nested blocks. In those rare cases where you might use this property,\ it can help you adjust how a block is rendered. For example, you could render a block differently based on the number of nested blocks or if a specific block type is present.. ``` jsx save: ( { attributes, innerBlocks } ) => { let { className, ...rest } = useBlockProps.save(); // innerBlocks could also be an object - react element during initialization const numberOfInnerBlocks = innerBlocks?.length; if ( numberOfInnerBlocks > 1 ) { className = className + ( className ? ' ' : '' ) + 'more-than-one'; }; const blockProps = { ...rest, className }; return
{ attributes.content }
; }; ``` Here, an additional class is added to the block if number of inner blocks is greater than one, allowing for different styling of the block. ## Examples Here are a couple examples of using attributes, edit, and save all together. ### Saving Attributes to Child Elements ``` jsx attributes: { content: { type: 'string', source: 'html', selector: 'div' } }, edit: ( { attributes, setAttributes } ) => { const blockProps = useBlockProps(); const updateFieldValue = ( val ) => { setAttributes( { content: val } ); } return (

); }, save: ( { attributes } ) => { const blockProps = useBlockProps.save(); return
{ attributes.content }
; }, ``` ### Saving Attributes via Serialization Ideally, the attributes saved should be included in the markup. However, there are times when this is not practical, so if no attribute source is specified the attribute is serialized and saved to the block’s comment delimiter. This example could be for a dynamic block, such as the [Latest Posts block](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/latest-posts/index.js), which renders the markup server-side. The save function is still required, however in this case it simply returns null since the block is not saving content from the editor. ``` jsx attributes: { postsToShow: { type: 'number', } }, edit: ( { attributes, setAttributes } ) => { const blockProps = useBlockProps(); return (
{ setAttributes( { postsToShow: parseInt( val ) } ); }} />
); }, save: () => { return null; } ``` ## Validation When the editor loads, all blocks within post content are validated to determine their accuracy in order to protect against content loss. This is closely related to the saving implementation of a block, as a user may unintentionally remove or modify their content if the editor is unable to restore a block correctly. During editor initialization, the saved markup for each block is regenerated using the attributes that were parsed from the post’s content. If the newly-generated markup does not match what was already stored in post content, the block is marked as invalid. This is because we assume that unless the user makes edits, the markup should remain identical to the saved content. If a block is detected to be invalid, the user will be prompted to choose how to handle the invalidation: Clicking the **Attempt Block Recovery** button will attempt a recovery action as much as possible. Clicking the “3-dot” menu on the side of the block displays three options: - **Resolve**: Open Resolve Block dialog box with two buttons: - **Convert to HTML**: Protects the original markup from the saved post content and converts the block from its original type to the HTML block type, enabling the user to modify the HTML markup directly. - **Convert to Blocks**: Protects the original markup from the saved post content and converts the block from its original type to the validated block type. - **Convert to HTML**: Protects the original markup from the saved post content and converts the block from its original type to the HTML block type, enabling the user to modify the HTML markup directly. - **Convert to Classic Block**: Protects the original markup from the saved post content as correct. Since the block will be converted from its original type to the Classic block type, it will no longer be possible to edit the content using controls available for the original block type. ### Validation FAQ **How do blocks become invalid?** The two most common sources of block invalidations are: 1. A flaw in a block’s code would result in unintended content modifications. See the question below on how to debug block invalidation as a plugin author. 2. You or an external editor changed the HTML markup of the block in such a way that it is no longer considered correct. **I’m a plugin author. What should I do to debug why my blocks are being marked as invalid?** Before starting to debug, be sure to familiarize yourself with the validation step described above documenting the process for detecting whether a block is invalid. A block is invalid if its regenerated markup does not match what is saved in post content, so often this can be caused by the attributes of a block being parsed incorrectly from the saved content. If you’re using [attribute sources](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/), be sure that attributes sourced from markup are saved exactly as you expect, and in the correct type (usually a `'string'` or `'number'`). When a block is detected as invalid, a warning will be logged into your browser’s developer tools console. The warning will include specific details about the exact point at which a difference in markup occurred. Be sure to look closely at any differences in the expected and actual markups to see where problems are occurring. **I’ve changed my block’s `save` behavior and old content now includes invalid blocks. How can I fix this?** Refer to the guide on [Deprecated Blocks](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) to learn more about how to accommodate legacy content in intentional markup changes. # Attributes Block attributes provide information about the data stored by a block. For example, rich content, a list of image URLs, a background color, or a button title. A block can contain any number of attributes, and these are specified by the `attributes` field – an object where each key is the name of the attribute, and the value is the attribute definition. The attribute definition will contain, at a minimum, either a `type` or an `enum`. There may be additional fields. *Example*: Attributes object defining three attributes – `url`, `title`, and `size`. ``` js { url: { type: 'string', source: 'attribute', selector: 'img', attribute: 'src', }, title: { type: 'string', }, size: { enum: [ 'large', 'small' ], }, } ``` When a block is parsed this definition will be used to extract data from the block content. Anything that matches will be available to your block through the `attributes` prop. This parsing process can be summarized as: 1. Extract value from the `source`. 2. Check value matches the `type`, or is one of the `enum` values. *Example*: Attributes available in the `edit` and function, using the above attributes definition. ``` js function YourBlockEdit( { attributes } ) { return (
URL is { attributes.url }, title is { attributes.title }, and size is { attributes.size }.
) } ``` The block is responsible for using the `save` function to ensure that all attributes with a `source` field are saved according to the attributes definition. This is not automatic. Attributes without a `source` will be automatically saved in the block [comment delimiter](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes). For example, using the above attributes definition you would need to ensure that your `save` function has a corresponding img tag for the `url` attribute. The `title` and `size` attributes will be saved in the comment delimiter. *Example*: Example `save` function that contains the `url` attribute. ``` js function YourBlockSave( { attributes } ) { return ( ) } ``` The saved HTML will contain the `title` and `size` in the comment delimiter, and the `url` in the `img` node. ``` html ``` If an attribute changes over time then a [block deprecation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) can help migrate from an older attribute, or remove it entirely. ## Type validation The `type` indicates the type of data that is stored by the attribute. It does not indicate where the data is stored, which is defined by the `source` field. A `type` is required, unless an `enum` is provided. A `type` can be used with an `enum`. The `type` field MUST be one of the following: - `null` - `boolean` - `object` - `array` - `string` - `integer` - `number` (same as `integer`) Note that the validity of an `object` is determined by your `source`. For an example, see the `query` details below. ## Enum validation An attribute can be defined as one of a fixed set of values. This is specified by an `enum`, which contains an array of allowed values: *Example*: Example `enum`. ``` js { size: { enum: [ 'large', 'small', 'tiny' ] } } ``` ## Value source Attribute sources are used to define how the attribute values are extracted from saved post content. They provide a mechanism to map from the saved markup to a JavaScript representation of a block. The available `source` values are:\ – `(no value)` – when no `source` is specified then data is stored in the block’s [comment delimiter](https://developer.wordpress.org/block-editor/explanations/architecture/key-concepts/#data-and-attributes).\ – `attribute` – data is stored in an HTML element attribute.\ – `text` – data is stored in HTML text.\ – `html` – data is stored in HTML. This is typically used by `RichText`.\ – `query` – data is stored as an array of objects.\ – `meta` – data is stored in post meta (deprecated). The `source` field is usually combined with a `selector` field. If no selector argument is specified, the source definition runs against the block’s root node. If a selector argument is specified, it will run against the matching element(s) within the block. The `selector` can be an HTML tag, or anything queryable with [querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector), such as a class or id attribute. Examples are given below. For example, a `selector` of `img` will match an `img` element, and `img.class` will match an `img` element that has a class of `class`. Under the hood, attribute sources are a superset of the functionality provided by [hpq](https://github.com/aduth/hpq), a small library used to parse and query HTML markup into an object shape. To summarize, the `source` determines where data is stored in your content, and the `type` determines what that data is. To reduce the amount of data stored it is usually better to store as much data as possible within HTML rather than as attributes within the comment delimiter. ### `attribute` source Use an `attribute` source to extract the value from an attribute in the markup. The attribute is specified by the `attribute` field, which must be supplied. *Example*: Extract the `src` attribute from an image found in the block’s markup. Saved content: ``` html
Block Content
``` Attribute definition: ``` js { url: { type: 'string', source: 'attribute', selector: 'img', attribute: 'src', } } ``` Attribute available in the block: ``` js { "url": "https://lorempixel.com/1200/800/" } ``` Most attributes from markup will be of type `string`. Numeric attributes in HTML are still stored as strings, and are not converted automatically. *Example*: Extract the `width` attribute from an image found in the block’s markup. Saved content: ``` html
Block Content
``` Attribute definition: ``` js { width: { type: 'string', source: 'attribute', selector: 'img', attribute: 'width', } } ``` Attribute available in the block: ``` js { "width": "50" } ``` The only exception is when checking for the existence of an attribute (for example, the `disabled` attribute on a `button`). In that case type `boolean` can be used and the stored value will be a boolean. *Example*: Extract the `disabled` attribute from a button found in the block’s markup. Saved content: ``` html
Block Content
``` Attribute definition: ``` js { disabled: { type: 'boolean', source: 'attribute', selector: 'button', attribute: 'disabled', } } ``` Attribute available in the block: ``` js { "disabled": true } ``` ### `text` source Use `text` to extract the inner text from markup. Note that HTML is returned according to the rules of [`textContent`](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent). *Example*: Extract the `content` attribute from a figcaption element found in the block’s markup. Saved content: ``` html

The inner text of the figcaption element

``` Attribute definition: ``` js { content: { type: 'string', source: 'text', selector: 'figcaption', } } ``` Attribute available in the block: ``` js { "content": "The inner text of the figcaption element" } ``` Another example, using `text` as the source, and using `.my-content` class as the selector to extract text: *Example*: Extract the `content` attribute from an element with `.my-content` class found in the block’s markup. Saved content: ``` html

The inner text of .my-content class

``` Attribute definition: ``` js { content: { type: 'string', source: 'text', selector: '.my-content', } } ``` Attribute available in the block: ``` js { "content": "The inner text of .my-content class" } ``` ### `html` source Use `html` to extract the inner HTML from markup. Note that text is returned according to the rules of [`innerHTML`](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML). *Example*: Extract the `content` attribute from a figcaption element found in the block’s markup. Saved content: ``` html

The inner text of the figcaption element

``` Attribute definition: ``` js { content: { type: 'string', source: 'html', selector: 'figcaption', } } ``` Attribute available in the block: ``` js { "content": "The inner text of the figcaption element" } ``` ### `query` source Use `query` to extract an array of values from markup. Entries of the array are determined by the `selector` argument, where each matched element within the block will have an entry structured corresponding to the second argument, an object of attribute sources. The `query` field is effectively a nested block attributes definition. It is possible (although not necessarily recommended) to nest further. *Example*: Extract `src` and `alt` from each image element in the block’s markup. Saved content: ``` html

``` Attribute definition: ``` js { images: { type: 'array', source: 'query', selector: 'img', query: { url: { type: 'string', source: 'attribute', attribute: 'src', }, alt: { type: 'string', source: 'attribute', attribute: 'alt', }, } } } ``` Attribute available in the block: ``` js { "images": [ { "url": "https://lorempixel.com/1200/800/", "alt": "large image" }, { "url": "https://lorempixel.com/50/50/", "alt": "small image" } ] } ``` ### Meta source (deprecated)
Although attributes may be obtained from a post’s meta, meta attribute sources are considered deprecated; [EntityProvider and related hook APIs](https://github.com/WordPress/gutenberg/blob/c367c4e2765f9e6b890d1565db770147efca5d66/packages/core-data/src/entity-provider.js) should be used instead, as shown in the [Create Meta Block how-to](https://developer.wordpress.org/block-editor/how-to-guides/metabox/#step-2-add-meta-block).
Attributes may be obtained from a post’s meta rather than from the block’s representation in saved post content. For this, an attribute is required to specify its corresponding meta key under the `meta` key. Attribute definition: ``` js { author: { type: 'string', source: 'meta', meta: 'author' }, }, ``` From here, meta attributes can be read and written by a block using the same interface as any attribute: ``` js edit( { attributes, setAttributes } ) { function onChange( event ) { setAttributes( { author: event.target.value } ); } return ; }, ``` #### Considerations By default, a meta field will be excluded from a post object’s meta. This can be circumvented by explicitly making the field visible: ``` php function gutenberg_my_block_init() { register_post_meta( 'post', 'author', array( 'show_in_rest' => true, ) ); } add_action( 'init', 'gutenberg_my_block_init' ); ``` Furthermore, be aware that WordPress defaults to: - not treating a meta datum as being unique, instead returning an array of values; - treating that datum as a string. If either behavior is not desired, the same `register_post_meta` call can be complemented with the `single` and/or `type` parameters as follows: ``` php function gutenberg_my_block_init() { register_post_meta( 'post', 'author_count', array( 'show_in_rest' => true, 'single' => true, 'type' => 'integer', ) ); } add_action( 'init', 'gutenberg_my_block_init' ); ``` If you’d like to use an object or an array in an attribute, you can register a `string` attribute type and use JSON as the intermediary. Serialize the structured data to JSON prior to saving, and then deserialize the JSON string on the server. Keep in mind that you’re responsible for the integrity of the data; make sure to properly sanitize, accommodate missing data, etc. Lastly, make sure that you respect the data’s type when setting attributes, as the framework does not automatically perform type casting of meta. Incorrect typing in block attributes will result in a post remaining dirty even after saving (*cf.* `isEditedPostDirty`, `hasEditedAttributes`). For instance, if `authorCount` is an integer, remember that event handlers may pass a different kind of data, thus the value should be cast explicitly: ``` js function onChange( event ) { props.setAttributes( { authorCount: Number( event.target.value ) } ); } ``` ## Default value A block attribute can contain a default value, which will be used if the `type` and `source` do not match anything within the block content. The value is provided by the `default` field, and the value should match the expected format of the attribute. *Example*: Example `default` values. ``` js { type: 'string', default: 'hello world' } ``` ``` js { type: 'array', default: [ { "url": "https://lorempixel.com/1200/800/", "alt": "large image" }, { "url": "https://lorempixel.com/50/50/", "alt": "small image" } ] } ``` ``` js { type: 'object', default: { width: 100, title: 'title' } } ``` ## Role The `role` property designates an attribute as being of a particular conceptual type. This property can be applied to any attribute to provide semantic meaning about how the attribute should be handled. Use `content` to designate the attribute as user-editable content. Blocks with attributes marked as `content` may be enabled for privileged editing in special circumstances such as content only locking.\ Use `local` to mark the attribute as temporary and non-persistable. Attributes marked as `local` are ignored by the Block Serializer and never saved to post content. *Example*: `content` role used by the paragraph block. ``` js { content: { type: 'string', source: 'html', selector: 'p', role: 'content', } } ``` *Example*: `local` role used for temporary data. ``` js { blob: { type: 'string', role: 'local', } } ``` Learn more in the [WordPress 6.7 dev note](https://make.wordpress.org/core/2024/10/20/miscellaneous-block-editor-changes-in-wordpress-6-7/#stabilized-role-property-for-block-attributes). # Templates A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow specifying a default initial state for an editor session. The scope of templates include: - Setting a default state dynamically on the client. (like `defaultBlock`) - Registered as a default for a given post type. Planned additions: - Saved and assigned to pages as “page templates”. - Defined in a `template.php` file or pulled from a custom post type (`wp_templates`) that is site specific. - As the equivalent of the theme hierarchy. ## API Templates can be declared in JS or in PHP as an array of blockTypes (block name and optional attributes). The first example in PHP creates a template for posts that includes an image block to start, you can add as many or as few blocks to your template as needed. PHP example: ``` php template = array( array( 'core/image' ), ); } add_action( 'init', 'myplugin_register_template' ); ``` The following example in JavaScript creates a new block using [InnerBlocks](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) and templates, when inserted creates a set of blocks based off the template. ``` js const el = React.createElement; const { registerBlockType } = wp.blocks; const { InnerBlocks } = wp.blockEditor; const BLOCKS_TEMPLATE = [ [ 'core/image', {} ], [ 'core/paragraph', { placeholder: 'Image Details' } ], ]; registerBlockType( 'myplugin/template', { title: 'My Template Block', category: 'widgets', edit: ( props ) => { return el( InnerBlocks, { template: BLOCKS_TEMPLATE, templateLock: false, } ); }, save: ( props ) => { return el( InnerBlocks.Content, {} ); }, } ); ``` See the [Meta Block Tutorial](https://developer.wordpress.org/block-editor/how-to-guides/metabox/#step-4-use-block-templates-optional) for a full example of a template in use. ## Block attributes To find a comprehensive list of all block attributes that you can define in a template, consult the block’s `block.json` file, and look at the `attributes` and `supports` values. For example, [packages/block-library/src/heading/block.json](https://github.com/WordPress/gutenberg/blob/c62ccd80c7c6abb85740cf8745439029bf0f4d35/packages/block-library/src/heading/block.json#L5-L25) shows that the block has a `level` attribute, and supports the `anchor` parameter. If you don’t have the Gutenberg plugin installed, you can find `block.json` files inside `wp-includes/blocks/heading/block.json`. ## Custom post types A custom post type can register its own template during registration: ``` php function myplugin_register_book_post_type() { $args = array( 'public' => true, 'label' => 'Books', 'show_in_rest' => true, 'template' => array( array( 'core/image', array( 'align' => 'left', ) ), array( 'core/heading', array( 'placeholder' => 'Add Author...', ) ), array( 'core/paragraph', array( 'placeholder' => 'Add Description...', ) ), ), ); register_post_type( 'book', $args ); } add_action( 'init', 'myplugin_register_book_post_type' ); ``` ## Locking Sometimes the intention might be to lock the template on the UI so that the blocks presented cannot be manipulated. This is achieved with a `template_lock` property. ``` php function myplugin_register_template() { $post_type_object = get_post_type_object( 'post' ); $post_type_object->template = array( array( 'core/paragraph', array( 'placeholder' => 'Add Description...', ) ), ); $post_type_object->template_lock = 'all'; } add_action( 'init', 'myplugin_register_template' ); ``` *Options:* - `contentOnly` — prevents all operations. Additionally, the block types that don’t have content are hidden from the list view and can’t gain focus within the block list. Unlike the other lock types, this is not overridable by children. - `all` — prevents all operations. It is not possible to insert new blocks, move existing blocks, or delete blocks. - `insert` — prevents inserting or removing blocks, but allows moving existing blocks. Lock settings can be inherited by InnerBlocks. If `templateLock` is not set in an InnerBlocks area, the locking of the parent InnerBlocks area is used. If the block is a top level block, the locking configuration of the current post type is used. ## Individual block locking Alongside template level locking, you can lock individual blocks; you can do this using a `lock` attribute on the attributes level. Block-level lock takes priority over the `templateLock` feature. Currently, you can lock moving and removing blocks. ``` js attributes: { // Prevent a block from being moved or removed. lock: { remove: true, move: true, } } ``` *Options:* - `remove` — Locks the ability of a block from being removed. - `move` — Locks the ability of a block from being moved. You can use this with `templateLock` to lock all blocks except a single block by using `false` in `remove` or `move`. ``` php $template = array( array( 'core/image', array( 'align' => 'left', ) ), array( 'core/heading', array( 'placeholder' => 'Add Author...', ) ), // Allow a Paragraph block to be moved or removed. array( 'core/paragraph', array( 'placeholder' => 'Add Description...', 'lock' => array( 'move' => false, 'remove' => false, ), ) ), ); ``` ## Nested templates Container blocks like the columns blocks also support templates. This is achieved by assigning a nested template to the block. ``` php $template = array( array( 'core/paragraph', array( 'placeholder' => 'Add a root-level paragraph', ) ), array( 'core/columns', array(), array( array( 'core/column', array(), array( array( 'core/image', array() ), ) ), array( 'core/column', array(), array( array( 'core/paragraph', array( 'placeholder' => 'Add an inner paragraph' ) ), ) ), ) ) ); ``` # Annotations
**Note:** This API is experimental, that means it is subject to non-backward compatible changes or removal in any future version.
Annotations are a way to highlight a specific piece in a post created with the block editor. Examples of this include commenting on a piece of text and spellchecking. Both can use the annotations API to mark a piece of text. ## API To see the API for yourself the easiest way is to have a block that is at least 200 characters long without formatting and putting the following in the console: ``` js wp.data.dispatch( 'core/annotations' ).addAnnotation( { source: 'my-annotations-plugin', blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ], richTextIdentifier: 'content', range: { start: 50, end: 100, }, } ); ``` The start and the end of the range should be calculated based only on the text of the relevant `RichText`. For example, in the following HTML position 0 will refer to the position before the capital S: ``` html Strong text ``` To help with determining the correct positions, the `wp.richText.create` method can be used. This will split a piece of HTML into text and formats. All available properties can be found in the API documentation of the `addAnnotation` action. The property `richTextIdentifier` is the identifier of the RichText instance the annotation applies to. This is necessary because blocks may have multiple rich text instances that are used to manage data for different attributes, so you need to pass this in order to highlight text within the correct one. For example the Paragraph block only has a single RichText instance, with the identifier `content`. The quote block type has 2 RichText instances, so if you wish to highlight text in the citation, you need to pass `citation` as the `richTextIdentifier` when adding an annotation. To target the quote content, you need to use the identifier `value`. Refer to the source code of the block type to find the correct identifier. ## Block annotation It is also possible to annotate a block completely. In that case just provide the `selector` property and set it to `block`. The default `selector` is `range`, which can be used for text annotation. ``` js wp.data.dispatch( 'core/annotations' ).addAnnotation( { source: 'my-annotations-plugin', blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ], selector: 'block', } ); ``` This doesn’t provide any styling out of the box, so you have to provide some CSS to make sure your annotation is shown: ``` css .is-annotated-by-my-annotations-plugin { outline: 1px solid black; } ``` ## Text annotation The text annotation is controlled by the `start` and `end` properties. Simple `start` and `end` properties don’t work for HTML, so these properties are assumed to be offsets within the `rich-text` internal structure. For simplicity you can think about this as if all HTML would be stripped out and then you calculate the `start` and the `end` of the annotation. # API Versions This document lists the changes made between the different API versions. ## Version 3 (\>= WordPress 6.3) - WordPress 6.3 introduced the iframed post editor when all registered blocks use Block API version 3 or higher and no traditional meta boxes are present. - WordPress 7.0 evaluates the blocks in the post content instead of all registered blocks when deciding whether to use the iframe. - Gutenberg 23.6 and WordPress 7.1 always use the iframe for the post editor, regardless of the `apiVersion` of the blocks in the post content. Adding version 3 support means that a block should work inside an iframe. Refer to the [iframe editor migration guide](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility/) for testing and migration guidance. ## Version 2 (\>= WordPress 5.6) - To render the block element wrapper for the block’s `edit` implementation, the block author must use the `useBlockProps()` hook. - The generated class names and styles are no longer added automatically to the saved markup for static blocks when `save` is processed. To include them, the block author must explicitly use `useBlockProps.save()` and add to their block wrapper. ## Version 1 Initial version. # Context Block context is a feature which enables ancestor blocks to provide values which can be consumed by descendent blocks within its own hierarchy. Those descendent blocks can inherit these values without resorting to hard-coded values and without an explicit awareness of the block which provides those values. This is especially useful in full-site editing where, for example, the contents of a block may depend on the context of the post in which it is displayed. A blogroll template may show excerpts of many different posts. Using block context, there can still be one single “Post Excerpt” block which displays the contents of the post based on an inherited post ID. If you are familiar with [React Context](https://react.dev/learn/passing-data-deeply-with-context), block context adopts many of the same ideas. In fact, the client-side block editor implementation of block context is a very simple application of React Context. Block context is also supported in server-side `render_callback` implementations, demonstrated in the examples below. ## Defining block context Block context is defined in the registered settings of a block. A block can provide a context value, or consume a value it seeks to inherit. ### Providing block context A block can provide a context value by assigning a `providesContext` property in its registered settings. This is an object which maps a context name to one of the block’s own attributes. The value corresponding to that attribute value is made available to descendent blocks and can be referenced by the same context name. Currently, block context only supports values derived from the block’s own attributes. This could be enhanced in the future to support additional sources of context values. ``` js attributes: { recordId: { type: 'number', }, }, providesContext: { 'my-plugin/recordId': 'recordId', }, ``` For a complete example, refer to the section below. #### Include a namespace As seen in the above example, it is recommended that you include a namespace as part of the name of the context key so as to avoid potential conflicts with other plugins or default context values provided by WordPress. The context namespace should be specific to your plugin, and in most cases can be the same as used in the name of the block itself. ### Consuming block context A block can inherit a context value from an ancestor provider by assigning a `usesContext` property in its registered settings. This should be assigned as an array of the context names the block seeks to inherit. ``` js registerBlockType('my-plugin/record-title', { title: 'Record Title', category: 'widgets', usesContext: ['my-plugin/recordId'], ``` ## Using block context Once a block has defined the context it seeks to inherit, this can be accessed in the implementation of `edit` (JavaScript) and `render_callback` (PHP). It is provided as an object (JavaScript) or associative array (PHP) of the context values which have been defined for the block. Note that a context value will only be made available if the block explicitly defines a desire to inherit that value. Note: Block Context is not available to `save`. ### JavaScript ``` js registerBlockType('my-plugin/record-title', { edit({ context }) { return 'The record ID: ' + context['my-plugin/recordId']; }, ``` ### PHP A block’s context values are available from the `context` property of the `$block` argument passed as the third argument to the `render_callback` function. ``` php register_block_type( 'my-plugin/record-title', array( 'render_callback' => function( $attributes, $content, $block ) { return 'The current record ID is: ' . $block->context['my-plugin/recordId']; }, ) ); ``` ## Example 1. Create a `record` block. npm init @wordpress/block --namespace my-plugin record cd record 1. Edit `src/index.js`. Insert the `recordId` attribute and `providesContext` property in the `registerBlockType` function and add the registration of the `record-title` block at the bottom: ``` js registerBlockType( 'my-plugin/record', { // ... cut ... attributes: { recordId: { type: 'number', }, }, providesContext: { 'my-plugin/recordId': 'recordId', }, /** * @see ./edit.js */ edit: Edit, /** * @see ./save.js */ save, } ); registerBlockType( 'my-plugin/record-title', { title: 'Record Title', category: 'widgets', usesContext: [ 'my-plugin/recordId' ], edit( { context } ) { return 'The record ID: ' + context[ 'my-plugin/recordId' ]; }, save() { return null; }, } ); ``` 1. Edit `src/edit.js` for the `record` block. Replace the `Edit` function with the following code: ``` js import { TextControl } from '@wordpress/components'; import { InnerBlocks } from '@wordpress/block-editor'; import { __ } from '@wordpress/i18n'; export default function Edit( props ) { const MY_TEMPLATE = [ [ 'my-plugin/record-title', {} ] ]; const { attributes: { recordId }, setAttributes, } = props; return (
setAttributes( { recordId: Number( val ) } ) } />
); } ``` 1. Edit `src/save.js` for the `record` block. Replace the `save` function with the following code: ``` js export default function save( props ) { return
The record ID: { props.attributes.recordId }
; } ``` 1. Create a new post and add the `record` block. If you type a number in the text box, you’ll see the same number is shown in the `record-title` block below it. # Deprecation > This page provides a comprehensive guide to the principles and usage of the Deprecation API. For an introduction check out the [tutorial on the basics of block deprecation](https://developer.wordpress.org/news/2023/03/block-deprecation-a-tutorial/) which can be found on the [Developer Blog](https://developer.wordpress.org/news/). When updating static blocks markup and attributes, block authors need to consider existing posts using the old versions of their block. To provide a good upgrade path, you can choose one of the following strategies: - Do not deprecate the block and create a new one (a different name) - Provide a “deprecated” version of the block allowing users opening these in the block editor to edit them using the updated block. A block can have several deprecated versions. A deprecation will be tried if the current state of a parsed block is invalid, or if the deprecation defines an `isEligible` function that returns true. Deprecations do not operate as a chain of updates in the way other software data updates, like database migrations, do. At first glance, it is easy to think that each deprecation is going to make the required changes to the data and then hand this new form of the block onto the next deprecation to make its changes. What happens instead is: 1. If the current `save` method does not produce a valid block the first deprecation in the deprecations array is passed the original saved content. 2. If its `save` method produces valid content this deprecation is used to parse the block attributes. If it has a `migrate` method it will also be run using the attributes parsed by the deprecation. 3. If the first deprecation’s `save` method does not produce a valid block the subsequent deprecations in the array are tried until one producing a valid block is encountered. 4. The attributes, and any innerBlocks, from the first deprecation to generate a valid block are then passed back to the current `save` method to generate new valid content for the block. 5. At this point the current block should now be in a valid state and the deprecations workflow stops. It is important to note that if a deprecation’s `save` method does not produce a valid block then it is skipped completely, including its `migrate` method, even if `isEligible` would return true for the given attributes. This means that if you have several deprecations for a block and want to perform a new migration, like moving content to `InnerBlocks`, you may need to update the `migrate` methods in multiple deprecations in order for the required changes to be applied to all previous versions of the block. It is also important to note that if a deprecation’s `save` method imports additional functions from other files, changes to those files may accidentally change the behavior of the deprecation. You may want to add a snapshot copy of these functions to the deprecations file instead of importing them in order to avoid inadvertently breaking the deprecations. For blocks with multiple deprecations, it may be easier to save each deprecation to a constant with the version of the block it applies to, and then add each of these to the block’s `deprecated` array. The deprecations in the array should be in reverse chronological order. This allows the block editor to attempt to apply the most recent and likely deprecations first, avoiding unnecessary and expensive processing. **Example** ``` js const v1 = {}; const v2 = {}; const v3 = {}; const deprecated = [ v3, v2, v1 ]; ``` It is also recommended to keep [fixtures](https://github.com/WordPress/gutenberg/blob/HEAD/test/integration/fixtures/blocks/README.md) which contain the different versions of the block content to allow you to easily test that new deprecations and migrations are working across all previous versions of the block. Deprecations are defined on a block type as its `deprecated` property, an array of deprecation objects where each object takes the form: - `attributes` (Object): The [attributes definition](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) of the deprecated form of the block. - `supports` (Object): The [supports definition](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/) of the deprecated form of the block. - `save` (Function): The [save implementation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) of the deprecated form of the block. - `migrate`: (Function, Optional). A function which, given the old attributes and inner blocks is expected to return either the new attributes or a tuple array of attributes and inner blocks compatible with the block. As mentioned above, a deprecation’s `migrate` will not be run if its `save` function does not return a valid block so you will need to make sure your migrations are available in all the deprecations where they are relevant. - *Parameters* - `attributes`: The block’s old attributes. - `innerBlocks`: The block’s old inner blocks. - *Return* - `Object | Array`: Either the updated block attributes or tuple array `[attributes, innerBlocks]`. - `isEligible`: (Function, Optional). A function which returns `true` if the deprecation can handle the block migration even if the block is valid. It is particularly useful in cases where a block is technically valid even once deprecated, but still requires updates to its attributes or inner blocks. This function is **not** called when the results of all previous deprecations’ save functions were invalid. - *Parameters* - `attributes`: The raw block attributes as parsed from the serialized HTML, and before the block type code is applied. - `innerBlocks`: The block’s current inner blocks. - `data`: An object containing properties representing the block node and its resulting block object. - `data.blockNode`: The raw form of the block as a result of parsing the serialized HTML. - `data.block`: The block object, which is the result of applying the block type to the `blockNode`. - *Return* - `boolean`: Whether or not this otherwise valid block is eligible to be migrated by this deprecation.
It’s important to note that `attributes`, `supports`, and `save` are not automatically inherited from the current version, since they can impact parsing and serialization of a block, so they must be defined on the deprecated object in order to be processed during a migration.
**Example** ``` js const { registerBlockType } = wp.blocks; const attributes = { text: { type: 'string', default: 'some random value', }, }; const supports = { className: false, }; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... other block properties go here attributes, supports, save( props ) { return
{ props.attributes.text }
; }, deprecated: [ { attributes, supports, save( props ) { return
{ props.attributes.text }
; }, }, ], } ); ``` In the example above we updated the markup of the block to use a `div` instead of `p`. ## Changing the attributes set Sometimes, you need to update the attributes set to rename or modify old attributes. **Example** ``` js const { registerBlockType } = wp.blocks; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... other block properties go here attributes: { content: { type: 'string', default: 'some random value', }, }, save( props ) { return
{ props.attributes.content }
; }, deprecated: [ { attributes: { text: { type: 'string', default: 'some random value', }, }, migrate( { text } ) { return { content: text, }; }, save( props ) { return
{ props.attributes.text }
; }, }, ], } ); ``` In the example above we updated the markup of the block to use a `div` instead of `p` and rename the `text` attribute to `content`. ## Changing the innerBlocks Situations may exist where when migrating the block we may need to add or remove innerBlocks.\ E.g: a block wants to migrate a title attribute to a paragraph innerBlock. **Example** ``` js const { registerBlockType } = wp.blocks; registerBlockType( 'gutenberg/block-with-deprecated-version', { // ... block properties go here save( props ) { return
{ props.attributes.title }
; }, deprecated: [ { attributes: { title: { type: 'string', source: 'html', selector: 'p', }, }, migrate( attributes, innerBlocks ) { const { title, ...restAttributes } = attributes; return [ restAttributes, [ createBlock( 'core/paragraph', { content: attributes.title, fontSize: 'large', } ), ...innerBlocks, ], ]; }, save( props ) { return
{ props.attributes.title }
; }, }, ], } ); ``` In the example above we updated the block to use an inner Paragraph block with a title instead of a title attribute. *Above are example cases of block deprecation. For more, real-world examples, check for deprecations in the [core block library](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src). Core blocks have been updated across releases and contain simple and complex deprecations.* # Metadata in block.json Starting with the WordPress 5.8 release, we recommend using the `block.json` metadata file as the canonical way to register block types with both PHP (server-side) and JavaScript (client-side). Here is an example `block.json` file that would define the metadata for a plugin creating a notice block. **Example:** ``` json { "$schema": "https://schemas.wp.org/trunk/block.json", "apiVersion": 3, "name": "my-plugin/notice", "title": "Notice", "category": "text", "parent": [ "core/group" ], "icon": "star", "description": "Shows warning, error or success notices...", "keywords": [ "alert", "message" ], "version": "1.0.3", "textdomain": "my-plugin", "attributes": { "message": { "type": "string", "source": "html", "selector": ".message" } }, "providesContext": { "my-plugin/message": "message" }, "usesContext": [ "groupId" ], "selectors": { "root": ".wp-block-my-plugin-notice" }, "supports": { "align": true }, "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "other", "label": "Other" } ], "example": { "attributes": { "message": "This is a notice!" } }, "variations": [ { "name": "example", "title": "Example", "attributes": { "message": "This is an example!" } } ], "editorScript": "file:./index.js", "script": "file:./script.js", "viewScript": [ "file:./view.js", "example-shared-view-script" ], "editorStyle": "file:./index.css", "style": [ "file:./style.css", "example-shared-style" ], "viewStyle": [ "file:./view.css", "example-view-style" ], "render": "file:./render.php" } ``` ## Benefits of using the metadata file The block definition allows code sharing between JavaScript, PHP, and other languages when processing block types stored as JSON, and registering blocks with the `block.json` metadata file provides multiple benefits on top of it. From a performance perspective, when themes support lazy loading assets, blocks registered with `block.json` will have their asset enqueuing optimized out of the box. The frontend CSS and JavaScript assets listed in the `style` or `script` properties will only be enqueued when the block is present on the page, resulting in reduced page sizes. Furthermore, because the [Block Type REST API Endpoint](https://developer.wordpress.org/rest-api/reference/block-types/) can only list blocks registered on the server, registering blocks server-side is recommended; using the `block.json` file simplifies this registration. The [WordPress Plugins Directory](https://wordpress.org/plugins/) can detect `block.json` files, highlight blocks included in plugins, and extract their metadata. If you wish to submit your block(s) to the Block Directory all blocks contained in your plugin must have a `block.json` file for the Block Directory to recognize them. Development is improved by using a defined schema definition file. Supported editors can provide help like tooltips, autocomplete, and schema validation. To use the schema, add the following to the top of the `block.json`. ``` json "$schema": "https://schemas.wp.org/trunk/block.json" ```
Check [Registration of a block](https://developer.wordpress.org/block-editor/getting-started/fundamentals-block-development/registration-of-a-block) to learn more about how to register a block using its metadata.
## Block API This section describes all the properties that can be added to the `block.json` file to define the behavior and metadata of block types. ### API version - Type: `number` - Optional - Localized: No - Property: `apiVersion` - Default: `1` ``` json { "apiVersion": 3 } ``` The version of the Block API used by the block. The most recent version is `3` and it was introduced in WordPress 6.3. See [the API versions documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/) for more details. ### Name - Type: `string` - Required - Localized: No - Property: `name` ``` json { "name": "core/heading" } ``` The name for a block is a unique string that identifies a block. Names have to be structured as `namespace/block-name`, where namespace is the name of your plugin or theme. **Note:** A block name can only contain lowercase alphanumeric characters, dashes, and at most one forward slash to designate the plugin-unique namespace prefix. It must begin with a letter. **Note:** This name is used on the comment delimiters as ``. Block types in the `core` namespace do not include a namespace when serialized. ### Title - Type: `string` - Required - Localized: Yes - Property: `title` ``` json { "title": "Heading" } ``` This is the display title for your block, which can be translated with our translation functions. The title will display in the Inserter and in other areas of the editor. **Note:** To keep your block titles readable and accessible in the UI, try to avoid very long titles. ### Category - Type: `string` - Optional - Localized: No - Property: `category` ``` json { "category": "text" } ``` Blocks are grouped into categories to help users browse and discover them. The core provided categories are: - text - media - design - widgets - theme - embed Plugins and Themes can also register [custom block categories](https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#managing-block-categories). An implementation should expect and tolerate unknown categories, providing some reasonable fallback behavior (e.g. a “text” category). ### Parent - Type: `string[]` - Optional - Localized: No - Property: `parent` ``` json { "parent": [ "my-block/product" ] } ``` Setting `parent` lets a block require that it is only available when nested within the specified blocks. For example, you might want to allow an ‘Add to Cart’ block to only be available within a ‘Product’ block. ### Ancestor - Type: `string[]` - Optional - Localized: No - Property: `ancestor` - Since: `WordPress 6.0.0` ``` json { "ancestor": [ "my-block/product" ] } ``` The `ancestor` property makes a block available inside the specified block types at any position of the ancestor block subtree. That allows, for example, to place a ‘Comment Content’ block inside a ‘Column’ block, as long as ‘Column’ is somewhere within a ‘Comment Template’ block. In comparison to the `parent` property blocks that specify their `ancestor` can be placed anywhere in the subtree whilst blocks with a specified `parent` need to be direct children. ### Allowed Blocks - Type: `string[]` - Optional - Localized: No - Property: `allowedBlocks` - Since: `WordPress 6.5.0` ``` json { "allowedBlocks": [ "my-block/product" ] } ``` The `allowedBlocks` specifies which block types can be the direct children of the block. For example, a ‘List’ block can allow only ‘List Item’ blocks as children. ### Icon - Type: `string` - Optional - Localized: No - Property: `icon` ``` json { "icon": "smile" } ``` An icon property should be specified to make it easier to identify a block. These can be any of [WordPress’ Dashicons](https://developer.wordpress.org/resource/dashicons/) (slug serving also as a fallback in non-js contexts). **Note:** It’s also possible to override this property on the client-side with the source of the SVG element. In addition, this property can be defined with JavaScript as an object containing background and foreground colors. These colors will appear with the icon when they are applicable e.g.: in the inserter. Custom SVG icons are automatically wrapped in the [wp.primitives.SVG](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-primitives/) component to add accessibility attributes (aria-hidden, role, and focusable). ### Description - Type: `string` - Optional - Localized: Yes - Property: `description` ``` json { "description": "Introduce new sections and organize content to help visitors" } ``` This is a short description for your block, which can be translated with our translation functions. This will be shown in the block inspector. ### Keywords - Type: `string[]` - Optional - Localized: Yes - Property: `keywords` - Default: `[]` ``` json { "keywords": [ "keyword1", "keyword2" ] } ``` Sometimes a block could have aliases that help users discover it while searching. For example, an image block could also want to be discovered by photo. You can do so by providing an array of unlimited terms (which are translated). ### Version - Type: `string` - Optional - Localized: No - Property: `version` - Since: `WordPress 5.8.0` ``` json { "version": "1.0.3" } ``` The current version number of the block, such as 1.0 or 1.0.3. It’s similar to how plugins are versioned. This field might be used with block assets to control cache invalidation, and when the block author omits it, then the installed version of WordPress is used instead. ### Text Domain - Type: `string` - Optional - Localized: No - Property: `textdomain` - Since: `WordPress 5.7.0` ``` json { "textdomain": "my-plugin" } ``` The [gettext](https://www.gnu.org/software/gettext/) text domain of the plugin/block. More information can be found in the [Text Domain](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#text-domains) section of the [How to Internationalize your Plugin](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/) page. ### Attributes - Type: `object` - Optional - Localized: No - Property: `attributes` - Default: `{}` ``` json { "attributes": { "cover": { "type": "string", "source": "attribute", "selector": "img", "attribute": "src" }, "author": { "type": "string", "source": "html", "selector": ".book-author" } } } ``` Attributes provide the structured data needs of a block. They can exist in different forms when they are serialized, but they are declared together under a common interface. See [the attributes documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/) for more details. ### Provides Context - Type: `object` - Optional - Localized: No - Property: `providesContext` - Default: `{}` Context provided for available access by descendants of blocks of this type, in the form of an object which maps a context name to one of the block’s own attributes. See [the block context documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/) for more details. ``` json { "providesContext": { "my-plugin/recordId": "recordId" } } ``` ### Context - Type: `string[]` - Optional - Localized: No - Property: `usesContext` - Default: `[]` Array of the names of context values to inherit from an ancestor provider. See [the block context documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/) for more details. ``` json { "usesContext": [ "message" ] } ``` ### Selectors - Type: `object` - Optional - Localized: No - Property: `selectors` - Default: `{}` - Since: `WordPress 6.3.0` Any custom CSS selectors, keyed by `root`, feature, or sub-feature, to be used\ when generating block styles for theme.json (global styles) stylesheets.\ Providing custom selectors allows more fine grained control over which styles\ apply to what block elements, e.g. applying typography styles only to an inner\ heading while colors are still applied on the outer block wrapper etc. See [the selectors documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-selectors/) for more details. ``` json { "selectors": { "root": ".my-custom-block-selector", "color": { "text": ".my-custom-block-selector p" }, "typography": { "root": ".my-custom-block-selector > h2", "text-decoration": ".my-custom-block-selector > h2 span" } } } ``` ### Supports - Type: `object` - Optional - Localized: No - Property: `supports` - Default: `{}` It contains a set of options to control features used in the editor. See [the supports documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) for more details. ### Block Styles - Type: `array` - Optional - Localized: Yes (`label` only) - Property: `styles` - Default: `[]` ``` json { "styles": [ { "name": "default", "label": "Default", "isDefault": true }, { "name": "other", "label": "Other" } ] } ``` Block styles can be used to provide alternative styles to block. It works by adding a class name to the block’s wrapper. Using CSS, a theme developer can target the class name for the block style if it is selected. Plugins and Themes can also register [custom block styles](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) for existing blocks. ### Example - Type: `object` - Optional - Localized: No - Property: `example` ``` json { "example": { "attributes": { "message": "This is a notice!" } } } ``` It provides structured example data for the block. This data is used to construct a preview for the block to be shown in the Inspector Help Panel when the user mouses over the block. See the [Example documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#example-optional) for more details. ### Variations - Type: `object[]|WPDefinedPath` ([learn more](#wpdefinedpath)) - Optional - Localized: Yes (`title`, `description`, and `keywords` of each variation only) - Property: `variations` - Since: `WordPress 5.9.0` ``` json { "variations": [ { "name": "example", "title": "Example", "attributes": { "level": 2, "message": "This is an example!" }, "scope": [ "block" ], "isActive": [ "level" ] } ] } ``` Block Variations is the API that allows a block to have similar versions of it, but all these versions share some common functionality. Each block variation is differentiated from the others by setting some initial attributes or inner blocks. Then at the time when a block is inserted these attributes and/or inner blocks are applied. *Note: In JavaScript you can provide a function for the `isActive` property, and a React element for the `icon`. In the `block.json` file both only support strings* Starting with version 6.7, it is possible to specify a PHP file in `block.json` that generates the list of block variations on the server side: ``` json { "variations": "file:./variations.php" } ``` That PHP file is expected to `return` an array that contains the block variations. Strings found in the variations returned from the PHP file will not be localized automatically; instead, use the `__()` function as usual. For example: ``` php true, 'name' => 'wordpress', 'title' => 'WordPress', 'icon' => 'wordpress', 'attributes' => array( 'service' => 'wordpress', ), 'isActive' => array( 'service' ) ), array( 'name' => 'mail', 'title' => __( 'Mail' ), 'keywords' => array( __( 'email' ), __( 'e-mail' ) ), 'icon' => 'mail', 'attributes' => array( 'service' => 'mail', ), 'isActive' => array( 'mail' ) ), ); ``` See [the variations documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/) for more details. ### Block Hooks - Type: `object` - Optional - Property: `blockHooks` - Since: `WordPress 6.4.0` ``` json { "blockHooks": { "my-plugin/banner": "after" } } ``` Block Hooks is an API that allows a block to automatically insert itself next to all instances of a given block type, in a relative position also specified by the “hooked” block. That is, a block can opt to be inserted before or after a given block type, or as its first or last child (i.e. to be prepended or appended to the list of its child blocks, respectively). Hooked blocks will appear both on the frontend and in the editor (to allow for customization by the user). The key is the name of the block (`string`) to hook into, and the value is the position to hook into (`string`). Take a look at the [Block Hooks documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#blockhooks-optional) for more info about available configurations. ### Editor script - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `editorScript` ``` json { "editorScript": "file:./index.js" } ``` Block type editor scripts definition. They will only be enqueued in the context of the editor. It’s possible to pass a script handle registered with the [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) function, a path to a JavaScript file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). *Note: An option to pass also an array of editor scripts exists since WordPress `6.1.0`.* ### Script - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `script` ``` json { "script": "file:./script.js" } ``` Block type frontend and editor scripts definition. They will be enqueued both in the editor and when viewing the content on the front of the site. It’s possible to pass a script handle registered with the [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) function, a path to a JavaScript file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). *Note: An option to pass also an array of scripts exists since WordPress `6.1.0`.* ### View script - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `viewScript` - Since: `WordPress 5.9.0` ``` json { "viewScript": [ "file:./view.js", "example-shared-view-script" ] } ``` Block type frontend scripts definition. They will be enqueued only when viewing the content on the front of the site. It’s possible to pass a script handle registered with the [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/) function, a path to a JavaScript file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). *Note: An option to pass also an array of view scripts exists since WordPress `6.1.0`.* ### View script module - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `viewScriptModule` - Since: `WordPress 6.5.0` ``` json { "viewScriptModule": [ "file:./view.js", "example-shared-script-module-id" ] } ``` Block type frontend script module definition. They will be enqueued only when viewing the content on the front of the site. It’s possible to pass a script module ID registered with the [`wp_register_script_module`](https://developer.wordpress.org/reference/functions/wp_register_script_module/) function, a path to a JavaScript module relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). WordPress scripts and WordPress script modules are not compatible at the moment. If frontend view assets depend on WordPress scripts, `viewScript` should be used. If they depend on WordPress script modules —the Interactivity API at this time— `viewScriptModule` should be used. [More functionality](https://core.trac.wordpress.org/ticket/60647) will gradually become available to Script Modules. *Note: Available since WordPress `6.5.0`.* ### Editor style - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `editorStyle` ``` json { "editorStyle": "file:./index.css" } ``` Block type editor styles definition. They will only be enqueued in the context of the editor. It’s possible to pass a style handle registered with the [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) function, a path to a CSS file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). *Note: An option to pass also an array of editor styles exists since WordPress `5.9.0`.* ### Style - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `style` ``` json { "style": [ "file:./style.css", "example-shared-style" ] } ``` Block type frontend and editor styles definition. They will be enqueued both in the editor and when viewing the content on the front of the site. It’s possible to pass a style handle registered with the [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) function, a path to a CSS file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). *Note: An option to pass also an array of styles exists since WordPress `5.9.0`.* ### View Style - Type: `WPDefinedAsset`\|`WPDefinedAsset[]` ([learn more](#wpdefinedasset)) - Optional - Localized: No - Property: `viewStyle` - Since: `WordPress 6.5.0` ``` json { "viewStyle": [ "file:./view.css", "example-view-style" ] } ``` Block type frontend styles definition. They will be enqueued only when viewing the content on the front of the site. It’s possible to pass a style handle registered with the [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/) function, a path to a CSS file relative to the `block.json` file, or a list with a mix of both ([learn more](#wpdefinedasset)). Frontend-only styles are especially useful for interactive blocks, to style parts that will only be visible after a user performs some action and where those styles will never be needed in the editor. You can start with using the `style` property to put all your common styles in one stylesheet. Only when you need editor-specific styling or frontend-specific styling, you can expand to `editorStyle` and `viewStyle`, but still keep the common part of your styling in the main stylesheet. ### Render - Type: `WPDefinedPath` ([learn more](#wpdefinedpath)) - Optional - Localized: No - Property: `render` - Since: `WordPress 6.1.0` ``` json { "render": "file:./render.php" } ``` PHP file to use when rendering the block type on the server to show on the front end. The following variables are exposed to the file: - `$attributes` (`array`): The block attributes. - `$content` (`string`): The block default content. - `$block` (`WP_Block`): The block instance. An example implementation of the `render.php` file defined with `render` could look like: ``` php
>
``` *Note: This file loads for every instance of the block type when rendering the page HTML on the server. Accounting for that is essential when declaring functions or classes in the file. The simplest way to avoid the risk of errors is to consume that shared logic from another file.* ## Assets ### `WPDefinedPath` The `WPDefinedPath` type is a subtype of string, where the value represents a path to a JavaScript, CSS or PHP file relative to where the `block.json` file is located. The path provided must be prefixed with `file:`. This approach is based on how npm handles [local paths](https://docs.npmjs.com/files/package.json#local-paths) for packages. **Example:** In `block.json`: ``` json { "render": "file:./render.php" } ``` ### `WPDefinedAsset` It extends `WPDefinedPath` for JavaScript and CSS files. An alternative to the file path would be a script handle, script module ID, or style handle referencing an already registered asset using WordPress helpers. **Example:** In `block.json`: ``` json { "editorScript": "file:./index.js", "script": "file:./script.js", "viewScriptModule": [ "file:./view.js", "example-registered-script-module-id" ], "editorStyle": "file:./index.css", "style": [ "file:./style.css", "example-shared-style" ], "viewStyle": [ "file:./view.css", "example-view-style" ] } ``` In the context of WordPress, when a block is registered with PHP, it will automatically register all scripts, script modules, and styles that are found in the `block.json` file and use file paths rather than asset handles. That’s why the `WPDefinedAsset` type has to offer a way to mirror the parameters necessary to register scripts, script modules, and styles using [`wp_register_script`](https://developer.wordpress.org/reference/functions/wp_register_script/), [`wp_register_script_module`](https://developer.wordpress.org/reference/functions/wp_register_script_module/), and [`wp_register_style`](https://developer.wordpress.org/reference/functions/wp_register_style/), and then assign these as handles or script module IDs associated with the block. It’s possible to provide an object which takes the following shape: - `handle` (`string`) – the name of the script. If omitted, it will be auto-generated. - `dependencies` (`string[]`\|`{ id: string, import?: 'dynamic'|'static' }[]`) – an array of registered script handles this script depends on. Script modules may use a simple string for static dependencies or the object form to indicate a dynamic dependency. Dynamic dependencies are dependencies that may or may not be used at runtime and are typically used with the dynamic `import('module-id')` syntax. Default value: `[]`. - `version` (`string`\|`false`\|`null`) – string specifying the script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If the version is set to `false`, a version number is automatically added equal to the currently installed WordPress version. If set to `null`, no version is added. Default value: `false`. The definition is stored inside a separate PHP file which ends with `.asset.php` and is located next to the JS/CSS file listed in `block.json`. WordPress will automatically detect this file through pattern matching. This option is the preferred one as it is expected it will become an option to auto-generate those asset files with `@wordpress/scripts` package. **Example:** build/ ├─ block.json ├─ index.js └─ index.asset.php In `block.json`: ``` json { "editorScript": "file:./index.js" } ``` In `build/index.asset.php`: ``` php array( 'react', 'wp-blocks', 'wp-i18n', ), 'version' => '3be55b05081a63d8f9d0ecb466c42cfd', ); ``` ### Frontend enqueueing Starting in the WordPress 5.8 release, it is possible to instruct WordPress to enqueue scripts and styles for a block type only when rendered on the frontend. It applies to the following asset fields in the `block.json` file: - `script` - `viewScript` - `style` - `viewStyle` (Added in WordPress 6.5.0) ## Internationalization WordPress string discovery system can automatically translate fields marked in this document as translatable. First, you need to set the `textdomain` property in the `block.json` file that provides block metadata. **Example:** ``` json { "title": "My block", "description": "My block is fantastic", "keywords": [ "fantastic" ], "textdomain": "my-plugin" } ``` ### PHP In PHP, localized properties will be automatically wrapped in `_x` function calls on the backend of WordPress when executing `register_block_type`. These translations get added as an inline script to the plugin’s script handle or to the `wp-block-library` script handle in WordPress core. The way `register_block_type` processes translatable values is roughly equivalent to the following code snippet: ``` php _x( 'My block', 'block title', 'my-plugin' ), 'description' => _x( 'My block is fantastic!', 'block description', 'my-plugin' ), 'keywords' => array( _x( 'fantastic', 'block keyword', 'my-plugin' ) ), ); ``` Implementation follows the existing [get_plugin_data](https://developer.wordpress.org/reference/functions/get_plugin_data) function which parses the plugin contents to retrieve the plugin’s metadata, and it applies translations dynamically. ### JavaScript In JavaScript, you can use `registerBlockType` method from `@wordpress/blocks` package and pass the metadata object loaded from `block.json` as the first param. All localized properties get automatically wrapped in `_x` (from `@wordpress/i18n` package) function calls similar to how it works in PHP. **Example:** ``` js import { registerBlockType } from '@wordpress/blocks'; import Edit from './edit'; import metadata from './block.json'; registerBlockType( metadata, { edit: Edit, // ...other client-side settings } ); ``` ## Backward compatibility The existing registration mechanism (both server side and frontend) will continue to work, it will serve as low-level implementation detail for the `block.json` based registration. Once all details are ready, Core Blocks will be migrated iteratively and third-party blocks will see warnings appearing in the console to encourage them to refactor the block registration API used. The following properties are going to be supported for backward compatibility reasons on the client-side only. Some of them might be replaced with alternative APIs in the future: - `edit` – see the [Edit and Save](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) documentation for more details. - `save` – see the [Edit and Save](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/) documentation for more details. - `transforms` – see the [Transforms](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#transforms-optional) documentation for more details. - `deprecated` – see the [Deprecated Blocks](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/) documentation for more details. - `merge` – undocumented as of today. Its role is to handle merging multiple blocks into one. - `getEditWrapperProps` – undocumented as well. Its role is to inject additional props to the block edit’s component wrapper. **Example**: ``` js import { registerBlockType } from '@wordpress/blocks'; registerBlockType( 'my-plugin/block-name', { edit: function () { // Edit definition goes here. }, save: function () { // Save definition goes here. }, getEditWrapperProps: function () { // Implementation goes here. }, } ); ``` In the case of [dynamic blocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/) supported by WordPress, it should still be possible to register the `render_callback` property using both [`register_block_type`](https://developer.wordpress.org/reference/functions/register_block_type/) functions on the server. # Patterns Block Patterns are predefined block layouts available from the patterns tab of the block inserter. Once inserted into content, the blocks are ready for additional or modified content and configuration. ## Block patterns ### register_block_pattern The editor comes with several core block patterns. Theme and plugin authors can register additional custom block patterns using the `register_block_pattern` helper function. The `register_block_pattern` helper function receives two arguments.\ – `title`: A machine-readable title with a naming convention of `namespace/title`.\ – `properties`: An array describing properties of the pattern. The properties available for block patterns are: - `title` (required): A human-readable title for the pattern. - `content` (required): Block HTML Markup for the pattern. - `description` (optional): A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does. The description will help users discover the pattern while searching. - `categories` (optional): An array of registered pattern categories used to group block patterns. Block patterns can be shown on multiple categories. A category must be registered separately in order to be used here. - `keywords` (optional): An array of aliases or keywords that help users discover the pattern while searching. - `viewportWidth` (optional): An integer specifying the intended width of the pattern to allow for a scaled preview of the pattern in the inserter. - `blockTypes` (optional): An array of block types that the pattern is intended to be used with. Each value needs to be the declared block’s `name`. - `postTypes` (optional): An array of post types that the pattern is restricted to be used with. The pattern will only be available when editing one of the post types passed on the array. For all the other post types, the pattern is not available at all. - `templateTypes` (optional): An array of template types where the pattern makes sense, for example, `404` if the pattern is for a 404 page, `single-post` if the pattern is for showing a single post. - `inserter` (optional): By default, all patterns will appear in the inserter. To hide a pattern so that it can only be inserted programmatically, set the `inserter` to `false`. - `source` (optional): A string that denotes the source of the pattern. For a plugin registering a pattern, pass the string `plugin`. For a theme, pass the string `theme`. The following code sample registers a block pattern named `my-plugin/my-awesome-pattern`: ``` php register_block_pattern( 'my-plugin/my-awesome-pattern', array( 'title' => __( 'Two buttons', 'my-plugin' ), 'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'my-plugin' ), 'content' => "\n
\n
" . esc_html__( 'Button One', 'my-plugin' ) . "
\n\n\n\n
" . esc_html__( 'Button Two', 'my-plugin' ) . "
\n
\n", ) ); ``` Note that `register_block_pattern()` should be called from a handler attached to the `init` hook. ``` php function my_plugin_register_my_patterns() { register_block_pattern( ... ); } add_action( 'init', 'my_plugin_register_my_patterns' ); ``` ## Unregistering block patterns ### unregister_block_pattern The `unregister_block_pattern` helper function allows a previously registered block pattern to be unregistered from a theme or plugin and receives one argument. - `title`: The name of the block pattern to be unregistered. The following code sample unregisters the block pattern named `my-plugin/my-awesome-pattern`: ``` php unregister_block_pattern( 'my-plugin/my-awesome-pattern' ); ``` *Note:* `unregister_block_pattern()` should be called from a handler attached to the init hook. ``` php function my_plugin_unregister_my_patterns() { unregister_block_pattern( ... ); } add_action( 'init', 'my_plugin_unregister_my_patterns' ); ``` ## Block pattern categories Block patterns can be grouped using categories. The block editor comes with bundled categories you can use on your custom block patterns. You can also register your own block pattern categories. ### register_block_pattern_category The `register_block_pattern_category` helper function receives two arguments. - `title`: A machine-readable title for the block pattern category. - `properties`: An array describing properties of the pattern category. The properties of the pattern categories include: - `label` (required): A human-readable label for the pattern category. The following code sample registers the category named `hero`: ``` php register_block_pattern_category( 'hero', array( 'label' => __( 'Hero', 'my-plugin' ) ) ); ``` *Note:* `register_block_pattern_category()` should be called from a handler attached to the init hook. The category will not show under Patterns unless a pattern has been assigned to that category. ``` php function my_plugin_register_my_pattern_categories() { register_block_pattern_category( ... ); } add_action( 'init', 'my_plugin_register_my_pattern_categories' ); ``` ### unregister_block_pattern_category The `unregister_block_pattern_category` helper function allows for a previously registered block pattern category to be unregistered from a theme or plugin and receives one argument. - `title`: The name of the block pattern category to be unregistered. The following code sample unregisters the category named `hero`: ``` php unregister_block_pattern_category( 'hero' ); ``` *Note:* `unregister_block_pattern_category()` should be called from a handler attached to the init hook. ``` php function my_plugin_unregister_my_pattern_categories() { unregister_block_pattern_category( ... ); } add_action( 'init', 'my_plugin_unregister_my_pattern_categories' ); ``` ## Block patterns contextual to block types and pattern transformations It is possible to attach a block pattern to one or more block types. This adds the block pattern as an available transform for that block type. Currently, these transformations are available only to simple blocks (blocks without inner blocks). In order for a pattern to be suggested, **every selected block must be present in the block pattern**. For instance: ``` php register_block_pattern( 'my-plugin/powered-by-wordpress', array( 'title' => __( 'Powered by WordPress', 'my-plugin' ), 'blockTypes' => array( 'core/paragraph' ), 'content' => '
Powered by WordPress
', ) ); ``` The above code registers a block pattern named `my-plugin/powered-by-wordpress` and shows the pattern in the “transform menu” of paragraph blocks. The transformation result will keep the paragraph’s existing content and apply the other attributes – in this case, the background and text color. As mentioned above, pattern transformations for simple blocks can also work if we have selected multiple blocks and there are matching contextual patterns to these blocks. Let’s see an example of a pattern where two block types are attached. ``` php register_block_pattern( 'my-plugin/powered-by-wordpress', array( 'title' => __( 'Powered by WordPress', 'my-plugin' ), 'blockTypes' => array( 'core/paragraph', 'core/heading' ), 'content' => '

Hi everyone

Powered by WordPress

', ) ); ``` In the above example, if we select **one of the two** block types, either a paragraph or a heading block, this pattern will be suggested by transforming the selected block using its content and will also add the remaining blocks from the pattern. If, on the other hand, we multi-select one paragraph and one heading block, both blocks will be transformed. Blocks can also use these contextual block patterns in other places. For instance, when inserting a new Query Loop block, the user is provided with a list of all patterns attached to the block. ## Semantic block patterns In block themes, you can also mark block patterns as “header” or “footer” patterns (template part areas). We call these “semantic block patterns”. These patterns are shown to the user when inserting or replacing header or footer template parts. Example: ``` php __( 'My Header', 'my-plugin' ), 'categories' => array( 'header' ), // Assigning the pattern the "header" area. 'blockTypes' => array( 'core/template-part/header' ), 'content' => 'Content of my block pattern', ) ); ``` # Registration Block registration API reference.
You can use the functions documented on this page to register a block with JavaScript only on the client, but the recommended method is to register new block types also with PHP on the server using the \`block.json\` metadata file. See [metadata documentation for complete information](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)\ \ [Learn how to create your first block](https://developer.wordpress.org/block-editor/getting-started/create-block/) for the WordPress block editor. From setting up your development environment, tools, and getting comfortable with the new development model, this tutorial covers all you need to know to get started with creating blocks.
## `registerBlockType` - **Type:** `Function` Every block starts by registering a new block type definition. To register, you use the `registerBlockType` function from the [`wp-blocks` package](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-blocks/#registerblocktype). The function takes two arguments, a block `name` and a block configuration object. ### Block Name - **Type:** `String` The name for a block is a unique string that identifies a block. Names have to be structured as `namespace/block-name`, where namespace is the name of your plugin or theme. ``` js // Registering my block with a unique name registerBlockType( 'my-plugin/book', {} ); ``` *Note:* A block name can only contain lowercase alphanumeric characters and dashes, and must begin with a letter. *Note:* This name is used on the comment delimiters as ``. Those blocks provided by core don’t include a namespace when serialized. #### Important: Choose Your Namespace Carefully Block names cannot be changed later without consequences. The block name is stored in the post content of every post using that block, so changing it requires editing all affected posts or running database scripts. #### Namespace Best Practices - Use your actual plugin/theme name: `my-awesome-plugin/block-name` - Avoid generic names like `editorial/`, `block/`, or `create-block/` - Use the same namespace for all blocks in your plugin/theme - Make it unique to prevent conflicts with other plugins ``` js // Good examples registerBlockType( 'my-company-blocks/hero', {} ); registerBlockType( 'awesome-gallery-plugin/slideshow', {} ); // Avoid these registerBlockType( 'create-block/example', {} ); // Too generic registerBlockType( 'block/content', {} ); // Too generic ``` *Note:* `registerBlockCollection()` only works with blocks from a single namespace. ### Block configuration - **Type:** `Object` \[ `{ key: value }` \] A block requires a few properties to be specified before it can be registered successfully. These are defined through a configuration object, which includes the following: #### title - **Type:** `String` This is the display title for your block, which can be translated with our translation functions. The title will display in the Inserter and in other areas of the editor. ``` js // Our data object title: __( 'Book' ); ``` *Note:* To keep your block titles readable and accessible in the UI, try to avoid very long titles. #### description (optional) - **Type:** `String` This is a short description for your block, which can be translated with our translation functions. This will be shown in the Block Tab in the Settings Sidebar. ``` js description: __( 'Block showing a Book card.' ); ``` #### category - **Type:** `String` \[ text \| media \| design \| widgets \| theme \| embed \] Blocks are grouped into categories to help users browse and discover them. The core provided categories are: - text - media - design - widgets - theme - embed ``` js // Assigning to the 'widgets' category category: 'widgets', ``` Plugins and Themes can also register [custom block categories](https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#managing-block-categories). #### icon (optional) - **Type:** `String` \| `Object` An icon property should be specified to make it easier to identify a block. These can be any of [WordPress’ Dashicons](https://developer.wordpress.org/resource/dashicons/), or a custom `svg` element. ``` js // Specifying a dashicon for the block icon: 'book-alt', // Specifying a custom svg for the block icon: , ``` **Note:** Custom SVG icons are automatically wrapped in the [`wp.primitives.SVG` component](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-primitives/) to add accessibility attributes (`aria-hidden`, `role`, and `focusable`). An object can also be passed as icon, in this case, icon, as specified above, should be included in the src property. Besides src the object can contain background and foreground colors, these colors will appear with the icon when they are applicable e.g.: in the inserter. ``` js icon: { // Specifying a background color to appear with the icon e.g.: in the inserter. background: '#7e70af', // Specifying a color for the icon (optional: if not set, a readable color will be automatically defined) foreground: '#fff', // Specifying an icon for the block src: , } , ``` #### keywords (optional) - **Type:** `Array` Sometimes a block could have aliases that help users discover it while searching. For example, an `image` block could also want to be discovered by `photo`. You can do so by providing an array of terms (which can be translated). ``` js // Make it easier to discover a block with keyword aliases. // These can be localised so your keywords work across locales. keywords: [ __( 'image' ), __( 'photo' ), __( 'pics' ) ], ``` #### styles (optional) - **Type:** `Array` Block styles can be used to provide alternative styles to block. It works by adding a class name to the block’s wrapper. Using CSS, a theme developer can target the class name for the block style if it is selected. ``` js // Register block styles. styles: [ // Mark style as default. { name: 'default', label: __( 'Rounded' ), isDefault: true }, { name: 'outline', label: __( 'Outline' ) }, { name: 'squared', label: __( 'Squared' ) }, ], ``` Plugins and Themes can also register [custom block styles](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) for existing blocks. #### attributes (optional) - **Type:** `Object` Attributes provide the structured data needs of a block. They can exist in different forms when they are serialized, but they are declared together under a common interface. ``` js // Specifying my block attributes attributes: { cover: { type: 'string', source: 'attribute', selector: 'img', attribute: 'src', }, author: { type: 'string', source: 'html', selector: '.book-author', }, pages: { type: 'number', }, }, ``` - **See: [Attributes](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/).** #### example (optional) - **Type:** `Object` Example provides structured example data for the block. This data is used to construct a preview for the block to be shown in the Inspector Help Panel when the user mouses over the block and in the Styles panel when the block is selected. The data provided in the example object should match the attributes defined. For example: ``` js example: { attributes: { cover: 'https://example.com/image.jpg', author: 'William Shakespeare', pages: 500 }, }, ``` If `example` is not defined, the preview will not be shown. So even if no attributes are defined, setting an empty example object `example: {}` will trigger the preview to show. It’s also possible to extend the block preview with inner blocks via `innerBlocks`. For example: ``` js example: { attributes: { cover: 'https://example.com/image.jpg', }, innerBlocks: [ { name: 'core/paragraph', attributes: { /* translators: example text. */ content: __( 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis.' ), }, }, ], }, ``` It’s also possible to define the width of the preview container in pixels via `viewportWidth`. For example: ``` js example: { attributes: { cover: 'https://example.com/image.jpg', }, viewportWidth: 800 }, ``` #### variations (optional) - **Type:** `Object[]` - **Since**: `WordPress 5.9.0` Similarly to how the block’s styles can be declared, a block type can define block variations that the user can pick from. The difference is that, rather than changing only the visual appearance, this field provides a way to apply initial custom attributes and inner blocks at the time when a block is inserted. See the [Block Variations API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/) for more details. #### supports (optional) - ***Type:*** `Object` Supports contains a set of options to control features used in the editor. See [the `supports` documentation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/) for more details. #### transforms (optional) - **Type:** `Object` Transforms provide rules for what a block can be transformed from and what it can be transformed to. A block can be transformed from another block, a shortcode, a regular expression, a file, or a raw DOM node. Take a look at the [Block Transforms API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-transforms/) for more info about each available transformation. #### parent (optional) - **Type:** `Array` - **Default:** `undefined` Blocks are able to be inserted into blocks that use [`InnerBlocks`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) as nested content. Sometimes it is useful to restrict a block so that it is only available in a specific location. For example, you might want to allow an ‘Add to Cart’ block to only be available within a ‘Product’ block. When `parent` is omitted, the block is not restricted by parent block type. Setting `parent` to an array of block names requires that the block is only available when nested directly inside one of the specified blocks. ``` js // Only allow this block when it is nested directly in a Columns block parent: [ 'core/columns' ], ``` #### ancestor (optional) - **Type:** `Array` - **Since**: `WordPress 6.0.0` The `ancestor` property makes a block available inside the specified block types at any position of the ancestor block subtree. That allows, for example, to place a ‘Comment Content’ block inside a ‘Column’ block, as long as ‘Column’ is somewhere within a ‘Comment Template’ block. In comparison to the `parent` property, blocks that specify their `ancestor` can be placed anywhere in the subtree whilst blocks with a specified `parent` need to be direct children. ``` js // Only allow this block when it is nested at any level in a Columns block. ancestor: [ 'core/columns' ], ``` #### allowedBlocks (optional) - **Type:** `Array` - **Since**: `WordPress 6.5.0` Setting the `allowedBlocks` property will limit which block types can be nested as direct children of the block. ``` js // Only allow the Columns block to be nested as direct child of this block allowedBlocks: [ 'core/columns' ], ``` #### blockHooks (optional) - **Type:** `Object` - **Since**: `WordPress 6.4.0` Block Hooks is an API that allows a block to automatically insert itself next to all instances of a given block type, in a relative position also specified by the “hooked” block. That is, a block can opt to be inserted before or after a given block type, or as its first or last child (i.e. to be prepended or appended to the list of its child blocks, respectively). Hooked blocks will appear both on the frontend and in the editor (to allow for customization by the user). The key is the name of the block (`string`) to hook into, and the value is the position to hook into (`string`). Allowed target values are: - `before` – inject before the target block. - `after` – inject after the target block. - `firstChild` – inject before the first inner block of the target container block. - `lastChild` – inject after the last inner block of the target container block. ``` js { blockHooks: { 'core/verse': 'before', 'core/spacer': 'after', 'core/column': 'firstChild', 'core/group': 'lastChild', } } ``` ## Block collections ## `registerBlockCollection` - **Type:** `Function` Blocks can be added to collections, grouping together all blocks from the same origin `registerBlockCollection` takes two parameters, `namespace` and an object of settings including `title` and `icon`. ### Namespace - **Type:** `String` This should match the namespace declared in the block name; the name of your plugin or theme. ### Settings #### Title - **Type:** `String` This will display in the block inserter section, which will list all blocks in this collection. #### Icon - **Type:** `Object` (Optional) An icon to display alongside the title in the block inserter. ``` js // Registering a block collection registerBlockCollection( 'my-plugin', { title: 'My Plugin' } ); ``` # Supports Block Supports is the API that allows a block to declare support for certain features. Opting into any of these features will register additional attributes on the block and provide the UI to manipulate that attribute. In order for the attribute to get applied to the block the generated properties get added to the wrapping element of the block. They get added to the object you get returned from the `useBlockProps` hook. `BlockEdit` function: ``` js function BlockEdit() { const blockProps = useBlockProps(); return
Hello World!
; } ``` `save` function: ``` js function BlockEdit() { const blockProps = useBlockProps.save(); return
Hello World!
; } ``` For dynamic blocks that get rendered via a `render_callback` in PHP you can use the `get_block_wrapper_attributes()` function. It returns a string containing all the generated properties and needs to get output in the opening tag of the wrapping block element. `render_callback` function: ``` php function render_block() { $wrapper_attributes = get_block_wrapper_attributes(); return sprintf( '
%2$s
', $wrapper_attributes, 'Hello World!' ); } ``` ## allowedBlocks ***Note:** Since WordPress 6.9.* - Type: `boolean` - Default value: `false` This property adds UI controls which enable the user to select allowed child blocks for a block container. To use this feature, pass `attributes.allowedBlocks` as the `allowedBlocks` property in the options object of `useInnerBlocksProps`. ``` js supports: { allowedBlocks: true } ``` ``` jsx import { useBlockProps, useInnerBlocksProps } from '@wordpress/block-editor'; function Edit( { attributes } ) { const { allowedBlocks } = attributes; const blockProps = useBlockProps(); const innerBlocksProps = useInnerBlocksProps( blockProps, { allowedBlocks } ); return
; } ``` ## anchor - Type: `boolean` - Default value: `false` Anchors let you link directly to a specific block on a page. This property adds a field to define an id for the block and a button to copy the direct link. ``` js // Declare support for anchor links. supports: { anchor: true } ``` ## autoRegister - Type: `boolean` - Default value: `false` Enables [PHP-only blocks](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/#php-only-blocks-with-auto-registration) to automatically appear in the block editor without requiring JavaScript registration. When set to `true`, blocks registered on the server with a `render_callback` will automatically be registered in the editor and use `ServerSideRender`. These blocks default to block API version 3 and are automatically upgraded if they’re using an older version. ``` php register_block_type( 'my-plugin/server-block', array( 'render_callback' => function( $attributes ) { $wrapper_attributes = get_block_wrapper_attributes(); return sprintf( '
Server content
', $wrapper_attributes ); }, 'supports' => array( 'autoRegister' => true, ), ) ); ``` ## align - Type: `boolean` or `array` - Default value: `false` This property adds block controls, which enable changes to a block’s alignment. ``` js supports: { // Declare support for block's alignment. // This adds support for all the options: // left, center, right, wide, and full. align: true } ``` ``` js supports: { // Declare support for specific alignment options. align: [ 'left', 'right', 'full' ] } ``` When the block declares support for `align`, the attributes definition is extended to include an align attribute with a `string` type. By default, no alignment is assigned. The block can apply a default alignment by specifying its own `align` attribute with a default. For example: ``` js attributes: { align: { type: 'string', default: 'right' } } ``` ## alignWide - Type: `boolean` - Default value: `true` This property allows to enable [wide alignment](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#wide-alignment) for your theme. To disable this behavior for a single block, set this flag to `false`. ``` js supports: { // Remove the support for wide alignment. alignWide: false } ``` ## ariaLabel - Type: `boolean` - Default value: `false` ARIA-labels let you define an accessible label for elements. This property allows enabling the definition of an aria-label for the block, without exposing a UI field. ``` js supports: { // Add support for an aria label. ariaLabel: true } ``` ## background ***Note:** Since WordPress 6.5.* - Type: `Object` - Default value: `null` - Subproperties - `backgroundImage`: type `boolean`, default value `false` - `backgroundSize`: type `boolean`, default value `false` - `backgroundClip`: type `boolean`, default value `false` *(since WordPress 7.2)* This value signals that a block supports some of the CSS style properties related to background. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/#opt-in-into-ui-controls). `backgroundImage` adds UI controls which allow the user to select a background image.\ `backgroundSize` adds the FocalPointPicker to pick the position of the background image and allow the user to select the background size (cover, contain, fixed).\ `backgroundClip` sets which box the background is painted into, and can clip it to the block’s text. ``` js supports: { background: { backgroundImage: true // Enable background image control. backgroundSize: true, // Enable background image + size control. backgroundClip: true // Enable background clip. } } ``` Declaring `backgroundClip` alongside `gradient` gives the block a text gradient. The Typography panel then offers a Gradient control that fills the text, storing the gradient in `style.background.gradient` and `text` in `style.background.backgroundClip`. A block with a text gradient is not given the `has-background` class, because the gradient paints the text rather than the block’s background. Which clip values may be used is a theme’s decision, through `settings.background.backgroundClip`. It takes `true` for every value, `false` for none, or an array naming the ones to allow, for example `[ "border-box", "text" ]`. A block declaring the support only stands in where a theme has not set it. The clip control appears only when a value other than `text` is allowed, since the Typography panel’s Gradient control already expresses the text value. When a block declares support for a specific background property, its attributes definition is extended to include the `style` attribute. When a background image is selected, the image data is stored in the `style.background.backgroundImage`. When a background images is selected and its position or size are changed, the background-position is stored in the `style.background.backgroundPosition` and its background-size in `style.background.backgroundSize` attribute. - `style`: an attribute of `object` type with no default assigned. This is added when `backgroundImage` or `backgroundSize` support is declared. It stores the custom values set by the user. - `background`: an attribute of `object` type. - `backgroundImage`: an attribute of `object` type, containing information about the selected image - `url`: type `string`, URL to the image - `id`: type `int`, media attachment ID - `source`: type `string`, at the moment the only value is `file` - `title`: type `string`, title of the media attachment - `backgroundPosition`: an attribute of `string` type, defining the background images position, selected by FocalPointPicker and used in CSS as the [`background-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) value. - `backgroundSize`: an attribute of `string` type. defining the CSS [`background-size`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) value. - `backgroundClip`: an attribute of `string` type, defining the CSS [`background-clip`](https://developer.mozilla.org/en-US/docs/Web/CSS/background-clip) value. One of `border-box`, `padding-box`, `content-box` or `text`. The block can apply a default background image, position and size by specifying its own attribute with a default. For example: ``` js attributes: { style: { background: { backgroundImage: { "url":"IMAGE_URL" } backgroundPosition:"50% 50%", backgroundSize: "cover" } } } ``` ## className - Type: `boolean` - Default value: `true` By default, the class `.wp-block-your-block-name` is added to the root element of your saved markup. This helps by providing a consistent mechanism for styling blocks that themes and plugins can rely on. If, for whatever reason, a class is not desired on the markup, this functionality can be disabled. ``` js supports: { // Remove the support for the generated className. className: false } ``` ## color - Type: `Object` - Default value: null - Subproperties: - `background`: type `boolean`, default value `true` - `button`: type `boolean`, default value `false` - `enableContrastChecker`: type `boolean`, default value `true` - `gradients`: type `boolean`, default value `false` - `heading`: type `boolean`, default value `false` - `link`: type `boolean`, default value `false` - `text`: type `boolean`, default value `true` This value signals that a block supports some of the properties related to color. When this value is present, the block editor will show UI controls for the user to set their values. Note that the `background` and `text` keys have a default value of `true`, so if the `color` property is present they will also be considered enabled: ``` js supports: { color: { // This also enables text and background UI controls. gradients: true // Enables the gradients UI control. } } ``` It’s possible to disable them individually: ``` js supports: { color: { // Text UI control is enabled. background: false, // Disables the background UI control. gradients: true // Enables the gradients UI control. } } ``` ### color.background This property adds UI controls which allow the user to apply a solid background color to a block. When color support is declared, this property is enabled by default (along with text), so simply setting color will enable background color. ``` js supports: { color: true // Enables background and text color support. } ``` To disable background support while keeping other color supports enabled, set to `false`. ``` js supports: { color: { // Disables background support. Text color support is still enabled. background: false } } ``` When the block declares support for `color.background`, the attributes definition is extended to include two new attributes: `backgroundColor` and `style`: - `backgroundColor`: an attribute of `string` type with no default assigned. When a user chooses from the list of preset background colors, the preset slug is stored in the `backgroundColor` attribute. Background color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes). The block can apply a default preset background color by specifying its own attribute with a default. For example: ``` js attributes: { backgroundColor: { type: 'string', default: 'some-preset-background-slug', } } ``` - `style`: attribute of `object` type with no default assigned. When a custom background color is selected (i.e. using the custom color picker), the custom color value is stored in the `style.color.background` attribute. The block can apply a default custom background color by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { color: { background: '#aabbcc', } } } } ``` ### color.button ***Note:** Since WordPress 6.5.* This property adds block controls which allow the user to set button colors (text, background) in a block. Button colors are disabled by default. To enable button color support, set `color.button` to `true`. ``` js supports: { color: { button: true } } ``` Button color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes). When the block declares support for `color.button`, the attributes definition is extended to include the `style` attribute: - `style`: an attribute of `object` type with no default assigned. When a button color is selected, the color value is stored in the `style.elements.button.color.text` and `style.elements.button.color.background` attribute. The block can apply a default button colors by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { elements: { button: { color: { text: 'var:preset|color|contrast', background: '#000000', } } } } } } ``` ### color.enableContrastChecker ***Note:** Since WordPress 6.5.* Determines whether the contrast checker widget displays in the block editor UI. The contrast checker appears only if the block declares support for color. It tests the readability of color combinations and warns if there is a potential issue. The property is enabled by default. Set to `false` to explicitly disable: ``` js supports: { color: { enableContrastChecker: false } } ``` ### color.\_\_experimentalDuotone ***Note:** Deprecated since WordPress 6.3.* This property has been replaced by [`filter.duotone`](#filter-duotone). ### color.gradients This property adds UI controls which allow the user to apply a gradient background to a block. ``` js supports: { color: { gradients: true, // Default values must be disabled if you don't want to use them with gradients. background: false, text: false } } ``` Gradient presets are sourced from `editor-gradient-presets` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-gradient-presets). When the block declares support for `color.gradient`, the attributes definition is extended to include two new attributes: `gradient` and `style`: - `gradient`: an attribute of `string` type with no default assigned. When a user chooses from the list of preset gradients, the preset slug is stored in the `gradient` attribute. The block can apply a default preset gradient by specifying its own attribute with a default. For example: ``` js attributes: { gradient: { type: 'string', default: 'some-preset-gradient-slug', } } ``` - `style`: an attribute of `object` type with no default assigned. When a custom gradient is selected (i.e. using the custom gradient picker), the custom gradient value is stored in the `style.color.gradient` attribute. The block can apply a default custom gradient by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { color: { gradient: 'linear-gradient(135deg,rgb(170,187,204) 0%,rgb(17,34,51) 100%)', } } } } ``` ### color.heading ***Note:** Since WordPress 6.5.* This property adds block controls which allow the user to set heading colors in a block. Heading colors are disabled by default. To enable heading color support, set `color.heading` to `true`. ``` js supports: { color: { // Enable heading color support. heading: true } } ``` Heading color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes). When the block declares support for `color.heading`, the attributes definition is extended to include the `style` attribute: - `style`: an attribute of `object` type with no default assigned. When a heading color is selected, the color value is stored in the `style.elements.heading.color.text` and `style.elements.heading.color.background` attribute. The block can apply default heading colors by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { elements: { heading: { color: { text: 'var:preset|color|contrast', background: '#000000', } } } } } } ``` ### color.link This property adds block controls which allow the user to set link colors in a block. Link colors are disabled by default. To enable link color support, set `color.link` to `true`. ``` js supports: { color: { link: true } } ``` Link color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes). When the block declares support for `color.link`, the attributes definition is extended to include the `style` attribute: - `style`: an attribute of `object` type with no default assigned. When a link color is selected, the color value is stored in the `style.elements.link.color.text` and `style.elements.link.:hover.color.text` attribute. The block can apply default link colors by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { elements: { link: { color: { text: 'var:preset|color|contrast', }, ":hover": { color: { text: "#000000" } } } } } } } ``` ### color.text This property adds block controls which allow the user to set text color in a block. When color support is declared, this property is enabled by default (along with background), so simply setting color will enable text color. ``` js supports: { color: true // Enables background and text, but not link. } ``` To disable text color support while keeping other color supports enabled, set `color.text` to `false`. ``` js supports: { color: { // Disable text color support. text: false } } ``` Text color presets are sourced from the `editor-color-palette` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-color-palettes). When the block declares support for `color.text`, the attributes definition is extended to include two new attributes: `textColor` and `style`: - `textColor`: an attribute of `string` type with no default assigned. When a user chooses from the list of preset text colors, the preset slug is stored in the `textColor` attribute. The block can apply a default preset text color by specifying its own attribute with a default. For example: ``` js attributes: { textColor: { type: 'string', default: 'some-preset-text-color-slug', } } ``` - `style`: an attribute of `object` type with no default assigned. When a custom text color is selected (i.e. using the custom color picker), the custom color value is stored in the `style.color.text` attribute. The block can apply a default custom text color by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { color: { text: '#aabbcc', } } } } ``` ## contentRole ***Note:** Since WordPress 6.9.* - Type: `boolean` - Default value: `false` Marks the block itself as content. It is intended primarily for blocks that do not declare `content` attributes, or whose content is expressed only through their inner blocks. When enabled, content-only editing modes can still edit these blocks and allow inner blocks to be added or removed. ``` js supports: { contentRole: true } ``` ## customClassName - Type: `boolean` - Default value: `true` This property adds a field to define a custom className for the block’s wrapper. ``` js supports: { // Remove the support for the custom className. customClassName: false } ``` ## dimensions ***Note:** Since WordPress 6.2.* - Type: `Object` - Default value: null - Subproperties: - `aspectRatio`: type `boolean`, default value `false` - `height`: type `boolean`, default value `false` - `minHeight`: type `boolean`, default value `false` - `minWidth`: type `boolean`, default value `false` - `width`: type `boolean`, default value `false` This value signals that a block supports some of the CSS style properties related to dimensions. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/#opt-in-into-ui-controls). ``` js supports: { dimensions: { aspectRatio: true, // Enable aspect ratio control. height: true, // Enable height control. minHeight: true, // Enable min height control. minWidth: true, // Enable min width control. width: true, // Enable width control. } } ``` When a block declares support for a specific dimensions property, its attributes definition is extended to include the `style` attribute. - `style`: an attribute of `object` type with no default assigned. This is added when `aspectRatio`, `height`, `minHeight`, `minWidth`, or `width` support is declared. It stores the custom values set by the user. For example: ``` js attributes: { style: { dimensions: { aspectRatio: "16/9", height: "40vh", minHeight: "50vh", minWidth: "200px", width: "400px", } } } ``` ## editableRoot - Type: `boolean` - Default value: `false` When set to `true`, the block declares that it keeps working when an ancestor\ element (the editor canvas) is the `contenteditable` editing host, with focus\ and the native selection residing there instead of on the block’s own editable\ elements. The editor uses this to keep the canvas editable while such a block\ is selected, enabling native partial selection across blocks. Blocks that rely\ on `event.target` or DOM focus pointing at their own elements should not\ declare this support. ## filter - Type: `Object` - Default value: null - Subproperties: - `duotone`: type `boolean`, default value `false` This value signals that a block supports some of the properties related to filters. When it does, the block editor will show UI controls for the user to set their values. ### filter.duotone This property adds UI controls which allow the user to apply a duotone filter to\ a block or part of a block. ``` js supports: { filter: { // Enable duotone support duotone: true } }, selectors: { filter: { // Apply the filter to img elements inside the image block duotone: '.wp-block-image img' } } ``` The filter can be applied to an element inside the block by setting the `selectors.filter.duotone` selector. Duotone presets are sourced from `color.duotone` in [theme.json](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/). When the block declares support for `filter.duotone`, the attributes definition is extended to include the attribute `style`: - `style`: an attribute of `object` type with no default assigned. The block can apply a default duotone color by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { color: { duotone: [ '#FFF', '#000' ] } } } } ``` ## html - Type: `boolean` - Default value: `true` By default, a block’s markup can be edited individually. To disable this behavior, set `html` to `false`. ``` js supports: { // Remove support for an HTML mode. html: false } ``` ## inserter - Type: `boolean` - Default value: `true` By default, all blocks will appear in the inserter, block transforms menu, Style Book, etc. To hide a block from all parts of the user interface so that it can only be inserted programmatically, set `inserter` to `false`. ``` js supports: { // Hide this block from the inserter. inserter: false } ``` ## interactivity - Type: `boolean` or `object` - Default value: `false` - Subproperties: - `clientNavigation`: type `boolean`, default value `false` - `interactive`: type `boolean`, default value `false` Indicates if the block is using Interactivity API features. The `clientNavigation` sub-property indicates whether a block is compatible with the Interactivity API client-side navigation. See the [Client-Side Navigation Compatibility](https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/core-concepts/client-side-navigation-compatibility/) guide for details. The `interactive` sub-property indicates whether the block is using the Interactivity API directives. If you set `supports.interactivity` to `true`, it is equivalent to setting both `supports.interactivity.clientNavigation` and `supports.interactivity.interactive` to `true` as well. ## layout - Type: `boolean` or `Object` - Default value: null - Subproperties: - `default`: type `Object`, default value null - `allowSwitching`: type `boolean`, default value `false` - `allowEditing`: type `boolean`, default value `true` - `allowInheriting`: type `boolean`, default value `true` - `allowSizingOnChildren`: type `boolean`, default value `false` - `allowVerticalAlignment`: type `boolean`, default value `true` - `allowJustification`: type `boolean`, default value `true` - `allowOrientation`: type `boolean`, default value `true` - `allowWrap`: type `boolean`, default value `true` - `allowCustomContentAndWideSize`: type `boolean`, default value `true` This value only applies to blocks that are containers for inner blocks. If set to `true` the layout type will be `flow`. For other layout types it’s necessary to set the `type` explicitly inside the `default` object. Note that for layout to work correctly, the block it applies to should have a classname as its selector. That classname will be concatenated with a layout type string to form the layout selector. ### layout.default - Type: `Object` - Default value: null Allows setting the `type` property to define what layout type is default for the block, and also default values for any properties inherent to that layout type. For example, for a `flex` layout, a default value can be set for `flexWrap`. ### layout.allowSwitching - Type: `boolean` - Default value: `false` Exposes a switcher control that allows toggling between all existing layout types. ### layout.allowEditing - Type: `boolean` - Default value: `true` Determines display of layout controls in the block sidebar. If set to false, layout controls will be hidden. ### layout.allowInheriting - Type: `boolean` - Default value: `true` For the `flow` layout type only, determines display of the “Inner blocks use content width” toggle. ### layout.allowSizingOnChildren - Type: `boolean` - Default value: `false` For the `flex` layout type only, determines display of sizing controls (Fit/Grow/Max width/Fixed) on all child blocks of the flex block. ### layout.allowVerticalAlignment - Type: `boolean` - Default value: `true` For the `flex` layout type only, determines display of the vertical alignment control in the block toolbar. ### layout.allowJustification - Type: `boolean` - Default value: `true` For the `flex` layout type, determines display of the justification control in the block toolbar and block sidebar. For the `constrained` layout type, determines display of justification control in the block sidebar. ### layout.allowOrientation - Type: `boolean` - Default value: `true` For the `flex` layout type only, determines display of the orientation control in the block toolbar. ### layout.allowWrap - Type: `boolean` - Default value: `true` For the `flex` layout type only, determines display of the “Allow to wrap to multiple lines” toggle in the block sidebar. When set to `false`, the wrap behavior is controlled by the `flexWrap` value in `layout.default`. ### layout.allowCustomContentAndWideSize - Type: `boolean` - Default value: `true` For the `constrained` layout type only, determines display of the custom content and wide size controls in the block sidebar. ## listView ***Note:** Since WordPress 7.0.* - Type: `boolean` - Default value: `false` Enables a List View panel in the block inspector for the block’s inner blocks. When this support is enabled, the inspector shows a List View tree allowing users to inspect and manage the block’s inner blocks from the sidebar instead of only using the global document List View. ``` js supports: { listView: true } ``` The `listView` support only affects the editor UI and does not add any attributes to the block. ## lock - Type: `boolean` - Default value: `true` A block may want to disable the ability to toggle the lock state. It can be locked/unlocked by a user from the block “Options” dropdown by default. To disable this behavior, set `lock` to `false`. ``` js supports: { // Remove support for locking UI. lock: false } ``` ## multiple - Type: `boolean` - Default value: `true` A non-multiple block can be inserted into each post, one time only. For example, the built-in ‘More’ block cannot be inserted again if it already exists in the post being edited. A non-multiple block’s icon is automatically dimmed (unclickable) to prevent multiple instances. ``` js supports: { // Use the block just once per post multiple: false } ``` ## position ***Note:** Since WordPress 6.2.* - Type: `Object` - Default value: null - Subproperties: - `sticky`: type `boolean`, default value `false` This value signals that a block supports some of the CSS style properties related to position. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/#opt-in-into-ui-controls). Note that sticky position controls are currently only available for blocks set at the root level of the document. Setting a block to the `sticky` position will stick the block to its most immediate parent when the user scrolls the page. ``` js supports: { position: { sticky: true // Enable selecting sticky position. } } ``` When the block declares support for a specific position property, its attributes definition is extended to include the `style` attribute. - `style`: an attribute of `object` type with no default assigned. This is added when `sticky` support is declared. It stores the custom values set by the user. For example: ``` js attributes: { style: { position: { type: "sticky", top: "0px" } } } ``` ## renaming ***Note:** Since WordPress 6.5.* - Type: `boolean` - Default value: `true` By default, a block can be renamed by a user from the block ‘Options’ dropdown or the ‘Advanced’ panel. To disable this behavior, set renaming to false. ``` js supports: { // Don't allow the block to be renamed in the editor. renaming: false, } ``` ## reusable - Type: `boolean` - Default value: `true` A block may want to disable the ability of being converted into a reusable block. By default all blocks can be converted to a reusable block. If supports reusable is set to false, the option to convert the block into a reusable block will not appear. ``` js supports: { // Don't allow the block to be converted into a reusable block. reusable: false, } ``` ## shadow ***Note:** Since WordPress 6.5.* - Type: `boolean` - Default value: `false` This property adds block controls which allow the user to set a box shadow for a block. Shadows are disabled by default. ``` js supports: { shadow: true // Enable the box-shadow picker. } ``` Shadow presets are sourced from the shadow presets defined in `theme.json`. When the block declares support for `shadow`, the attributes definition is extended to include the `style` attribute: - `style`: an attribute of `object` type with no default assigned. When a shadow is selected, the color value is stored in the `style.shadow`. The block can apply a default shadow by specifying its own attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { shadow: "var:preset|shadow|deep" } } } ``` ## spacing - Type: `Object` - Default value: null - Subproperties: - `margin`: type `boolean` or `array`, default value `false` - `padding`: type `boolean` or `array`, default value `false` - `blockGap`: type `boolean` or `array`, default value `false` This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values if [the theme declares support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#spacing-control). ``` js supports: { spacing: { margin: true, // Enable margin UI control. padding: true, // Enable padding UI control. blockGap: true, // Enables block spacing UI control for blocks that also use `layout`. } } ``` When the block declares support for a specific spacing property, its attributes definition is extended to include the `style` attribute. - `style`: an attribute of `object` type with no default assigned. This is added when `margin` or `padding` support is declared. It stores the custom values set by the user. For example: ``` js attributes: { style: { margin: 'value', padding: { top: 'value', } } } ``` A spacing property may define an array of allowable sides – ‘top’, ‘right’, ‘bottom’, ‘left’ – that can be configured. When such arbitrary sides are defined, only UI controls for those sides are displayed. Axial sides are defined with the `vertical` and `horizontal` terms, and display a single UI control for each axial pair (for example, `vertical` controls both the top and bottom sides). A spacing property may support arbitrary individual sides **or** axial sides, but not a mix of both. Note: `blockGap` accepts `vertical` and `horizontal` axial sides, which adjust gap column and row values. `blockGap` doesn’t support arbitrary sides. ``` js supports: { spacing: { margin: [ 'top', 'bottom' ], // Enable margin for arbitrary sides. padding: true, // Enable padding for all sides. blockGap: [ 'horizontal', 'vertical' ], // Enables axial (column/row) block spacing controls } } ``` ## typography - Type: `Object` - Default value: `null` - Subproperties: - `fontSize`: type `boolean`, default value `false` - `lineHeight`: type `boolean`, default value `false` - `textAlign`: type `boolean` or `array`, default value `false` - `textShadow`: type `boolean`, default value `false` The presence of this object signals that a block supports some typography related properties. When it does, the block editor will show a typography UI allowing the user to control their values. ``` js supports: { typography: { // Enable support and UI control for font-size. fontSize: true, // Enable support and UI control for line-height. lineHeight: true, // Enable support and UI control for text alignment. textAlign: true, }, } ``` ### typography.fontSize - Type: `boolean` - Default value: `false` This value signals that a block supports the font-size CSS style property. When it does, the block editor will show an UI control for the user to set its value. The values shown in this control are the ones declared by the theme via the `editor-font-sizes` [theme support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#block-font-sizes), or the default ones if none are provided. ``` js supports: { typography: { // Enable support and UI control for font-size. fontSize: true, }, } ``` When the block declares support for `fontSize`, the attributes definition is extended to include two new attributes: `fontSize` and `style`: - `fontSize`: an attribute of `string` type with no default assigned. It stores any preset value selected by the user. The block can apply a default fontSize by specifying its own `fontSize` attribute with a default. For example: ``` js attributes: { fontSize: { type: 'string', default: 'some-value', } } ``` - `style`: an attribute of `object` type with no default assigned. It stores the custom values set by the user and is shared with other block supports such as color. The block can apply a default style by specifying its own `style` attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { typography: { fontSize: 'value' } } } } ``` ### typography.lineHeight - Type: `boolean` - Default value: `false` This value signals that a block supports the line-height CSS style property. When it does, the block editor will show an UI control for the user to set its value if [the theme declares support](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#supporting-custom-line-heights). ``` js supports: { typography: { // Enable support and UI control for line-height. lineHeight: true, }, } ``` When the block declares support for `lineHeight`, the attributes definition is extended to include a new attribute `style` of `object` type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own `style` attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { typography: { lineHeight: 'value' } } } } ``` ### typography.textAlign ***Note:** Since WordPress 6.6.* - Type: `boolean` or `array` - Default value: `false` This property adds block toolbar controls which allow to change block’s text alignment. ``` js supports: { typography: { // Declare support for block's text alignment. // This adds support for all the options: // left, center, right. textAlign: true } } ``` ``` js supports: { typography: { // Declare support for specific text alignment options. textAlign: [ 'left', 'right' ] } } ``` When the block declares support for `textAlign`, the attributes definition is extended to include a new attribute `style` of `object` type with no default assigned. It stores the custom value set by the user. The block can apply a default style by specifying its own `style` attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { typography: { textAlign: 'value' } } } } ``` ### typography.textShadow - Type: `boolean` - Default value: `false` This value signals that a block supports the text-shadow CSS style property. When it does, the block editor will show a UI control for the user to set its value if the theme declares support. ``` js supports: { typography: { // Enable support and UI control for text-shadow. textShadow: true, }, } ``` When the block declares support for `textShadow`, the attributes definition is extended to include two new attributes: `textShadow` and `style`: - `textShadow`: an attribute of `string` type with no default assigned. It stores any preset value selected by the user. The block can apply a default preset text shadow by specifying its own `textShadow` attribute with a default. For example: ``` js attributes: { textShadow: { type: 'string', default: 'some-value', } } ``` - `style`: an attribute of `object` type with no default assigned. It stores the custom value set by the user and is shared with other block supports such as color. The block can apply a default style by specifying its own `style` attribute with a default. For example: ``` js attributes: { style: { type: 'object', default: { typography: { textShadow: 'value' } } } } ``` ## splitting When set to `true`, `Enter` will split the block into two blocks. Note that this\ is only meant for simple text blocks such as paragraphs and headings with a\ single `RichText` field. RichText in the `edit` function *must* have an\ `identifier` prop that matches the attribute key of the text, so that it updates\ the selection correctly and we know where to split. ## visibility ***Note:** Since WordPress 6.9.* - Type: `boolean` - Default value: `true` By default, a block can be hidden by a user from the block ‘Options’ dropdown. To disable this behavior, set visibility to false. ``` js supports: { visibility: false, } ``` # Transforms Block Transforms is the API that allows a block to be transformed *from* and *to* other blocks, as well as *from* other entities. Existing entities that work with this API include shortcodes, files, regular expressions, and raw DOM nodes. ## Transform direction: `to` and `from` A block declares which transformations it supports via the optional `transforms` key of the block configuration, whose subkeys `to` and `from` hold an array of available transforms for every direction. Example: ``` js export const settings = { title: 'My Block Title', description: 'My block description', /* ... */ transforms: { from: [ /* supported from transforms */ ], to: [ /* supported to transforms */ ], }, }; ``` ## Transformations types This section goes through the existing types of transformations blocks support: - block - enter - files - prefix - raw - shortcode ### Block This type of transformations support both *from* and *to* directions, allowing blocks to be converted into a different one. It has a corresponding UI control within the block toolbar. A transformation of type `block` is an object that takes the following parameters: - **type** *(string)*: the value `block`. - **blocks** *(array)*: a list of known block types. It also accepts the wildcard value (`"*"`), meaning that the transform is available to *all* block types (eg: all blocks can transform into `core/group`). - **transform** *(function)*: a callback that receives the attributes and inner blocks of the block being processed. It should return a block object or an array of block objects. - **variationName** *(string, optional)*: the name of the target block variation when the transform creates a variation of the transformed block type. This lets the transform UI show the variation title and icon instead of the base block type. - **isMatch** *(function, optional)*: a callback that receives the block attributes as the first argument and the block object as the second argument and should return a boolean. Returning `false` from this function will prevent the transform from being available and displayed as an option to the user. - **isMultiBlock** *(boolean, optional)*: whether the transformation can be applied when multiple blocks are selected. If true, the `transform` function’s first parameter will be an array containing each selected block’s attributes, and the second an array of each selected block’s inner blocks. False by default. - **priority** *(number, optional)*: controls the priority with which a transformation is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. - **shortcuts** *(array, optional)*: keyboard shortcuts that apply the transform to the selected block. See [Keyboard shortcuts](#keyboard-shortcuts) below. #### Keyboard shortcuts A transform of type `block` can declare keyboard shortcuts, which are registered with the editor’s keyboard shortcuts store and listed in the keyboard shortcuts help modal. Pressing the key combination transforms the selected block, as long as the block is fully editable. Each entry of `shortcuts` takes the following parameters: - **name** *(string)*: a unique and machine-readable shortcut name, e.g. `core/block-editor/transform-heading-to-paragraph`. - **description** *(string)*: a translated description, displayed in the keyboard shortcuts help modal. - **keyCombination** *(object)*: the key combination that triggers the shortcut, as a `character` and an optional `modifier` (one of the modifiers supported by the [`wp-keycodes` package](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-keycodes/), e.g. `access` or `primary`). - **aliases** *(array, optional)*: alternative key combinations that trigger the same shortcut. - **variationName** *(string, optional)*: the variation of the produced block the shortcut targets, defaulting to the transform’s own `variationName`. Declaring it per shortcut is what lets a single transform offer one shortcut per variation without appearing more than once in the block switcher. On a `to` transform the shortcuts apply to the block declaring them, and produce the first entry of `blocks`. On a `from` transform they apply to any block listed in `blocks`, and produce the block declaring them. **Example: transform a Heading block into a Paragraph block with Alt+Shift+0** ``` js transforms: { to: [ { type: 'block', blocks: [ 'core/paragraph' ], shortcuts: [ { name: 'core/block-editor/transform-heading-to-paragraph', description: __( 'Transform the selected heading into a paragraph.' ), keyCombination: { modifier: 'access', character: '0' }, }, ], transform: ( { content } ) => { return createBlock( 'core/paragraph', { content } ); }, }, ], }, ``` **Example: transform any block into a specific heading level** The Heading block hangs one shortcut per level on its single transform from Paragraph, so that Alt+Shift+2 on a paragraph produces an H2 while the block switcher still offers “Heading” once: ``` js transforms: { from: [ { type: 'block', blocks: [ 'core/paragraph' ], shortcuts: [ 1, 2, 3, 4, 5, 6 ].map( ( level ) => ( { name: `core/block-editor/transform-to-heading-${ level }`, description: /* … */, keyCombination: { modifier: 'access', character: `${ level }` }, variationName: `h${ level }`, } ) ), transform: ( { content } ) => createBlock( 'core/heading', { content } ), }, ], }, ``` Key combinations are matched globally, so a combination already claimed by another block or by the editor itself will not reliably reach your transform. In development builds a warning is logged when two blocks declare the same combination. To switch between variations of a block that is *already* of the target type, declare the shortcut on the [block variation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/#using-shortcut) instead. A shortcut that should do both — reach the variation from another block type and switch to it within the type — is declared in both places under the same `name`. **Example: from Paragraph block to Heading block** To declare this transformation we add the following code into the heading block configuration, which uses the `createBlock` function from the [`wp-blocks` package](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-blocks/#createblock). ``` js transforms: { from: [ { type: 'block', blocks: [ 'core/paragraph' ], transform: ( { content } ) => { return createBlock( 'core/heading', { content, } ); }, }, ] }, ``` **Example: blocks that have InnerBlocks** A block with InnerBlocks can also be transformed from and to another block with InnerBlocks. ``` js transforms: { to: [ { type: 'block', blocks: [ 'some/block-with-innerblocks' ], transform: ( attributes, innerBlocks ) => { return createBlock( 'some/other-block-with-innerblocks', attributes, innerBlocks ); }, }, ], }, ``` ### Enter This type of transformations support the *from* direction, allowing blocks to be created from some content introduced by the user. They’re applied in a new block line after the user has introduced some content and hit the ENTER key. A transformation of type `enter` is an object that takes the following parameters: - **type** *(string)*: the value `enter`. - **regExp** *(RegExp)*: the Regular Expression to use as a matcher. If the value matches, the transformation will be applied. - **transform** *(function)*: a callback that receives an object with a `content` field containing the value that has been entered. It should return a block object or an array of block objects. - **priority** *(number, optional)*: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. **Example: from — to Separator block** To create a separator block when the user types the hyphen three times and then hits the ENTER key we can use the following code: ``` js transforms = { from: [ { type: 'enter', regExp: /^-{3,}$/, transform: () => createBlock( 'core/separator' ), }, ], }; ``` ### Files This type of transformations support the *from* direction, allowing blocks to be created from files dropped into the editor. A transformation of type `files` is an object that takes the following parameters: - **type** *(string)*: the value `files`. - **transform** *(function)*: a callback that receives the array of files being processed. It should return a block object or an array of block objects. - **isMatch** *(function, optional)*: a callback that receives the array of files being processed and should return a boolean. Returning `false` from this function will prevent the transform from being applied. - **priority** *(number, optional)*: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. **Example: from file to File block** To create a File block when the user drops a file into the editor we can use the following code: ``` js transforms: { from: [ { type: 'files', isMatch: ( files ) => files.length === 1, // By defining a lower priority than the default of 10, // we make that the File block to be created as a fallback, // if no other transform is found. priority: 15, transform: ( files ) => { const file = files[ 0 ]; const blobURL = createBlobURL( file ); // File will be uploaded in componentDidMount() return createBlock( 'core/file', { href: blobURL, fileName: file.name, textLinkHref: blobURL, } ); }, }, ], } ``` ### Prefix This type of transformations support the *from* direction, allowing blocks to be created from some text typed by the user. They’re applied when, in a new block line, the user types some text and then adds a trailing space. A transformation of type `prefix` is an object that takes the following parameters: - **type** *(string)*: the value `prefix`. - **prefix** *(string)*: the character or sequence of characters that match this transform. - **transform** *(function)*: a callback that receives the content introduced. It should return a block object or an array of block objects. - **priority** *(number, optional)*: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. **Example: from text to custom block** If we want to create a custom block when the user types the question mark, we could use this code: ``` js transforms: { from: [ { type: 'prefix', prefix: '?', transform( content ) { return createBlock( 'my-plugin/question', { content, } ); }, }, ], } ``` ### Raw This type of transformation supports the *from* direction, allowing blocks to be created from raw HTML nodes. They’re applied when the user executes the “Convert to Blocks” action from within the block setting UI menu, as well as when some content is pasted or dropped into the editor. A transformation of type `raw` is an object that takes the following parameters: - **type** *(string)*: the value `raw`. - **transform** *(function, optional)*: a callback that receives the node being processed. It should return a block object or an array of block objects. - **schema** *(object\|function, optional)*: defines an [HTML content model](https://html.spec.whatwg.org/multipage/dom.html#content-models) used to detect and process pasted contents. See [below](#schemas-and-content-models). - **selector** *(string, optional)*: a CSS selector string to determine whether the element matches according to the [element.matches](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches) method. The transform won’t be executed if the element doesn’t match. This is a shorthand and alternative to using `isMatch`, which, if present, will take precedence. - **isMatch** *(function, optional)*: a callback that receives the node being processed and should return a boolean. Returning `false` from this function will prevent the transform from being applied. - **priority** *(number, optional)*: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set. **Example: from URLs to Embed block** If we want to create an Embed block when the user pastes some URL in the editor, we could use this code: ``` js transforms: { from: [ { type: 'raw', isMatch: ( node ) => node.nodeName === 'P' && /^\s*(https?:\/\/\S+)\s*$/i.test( node.textContent ), transform: ( node ) => { return createBlock( 'core/embed', { url: node.textContent.trim(), } ); }, }, ], } ``` #### Schemas and Content Models When pasting content it’s possible to define a [content model](https://html.spec.whatwg.org/multipage/dom.html#content-models) that will be used to validate and process pasted content. It’s often the case that HTML pasted into the editor will contain a mixture of elements that *should* transfer as well as elements that *shouldn’t*. For example, consider pasting `12:04 pm` into the editor. We want to copy `12:04 pm` and omit the `` and its `class` attribute because those won’t carry the same meaning or structure as they originally did from where they were copied. When writing `raw` transforms you can control this by supplying a `schema` which describes allowable content and which will be applied to clean up the pasted content before attempting to match with your block. The schemas are passed into [`cleanNodeList` from `@wordpress/dom`](https://github.com/wordpress/gutenberg/blob/trunk/packages/dom/src/dom/clean-node-list.ts); check there for a [complete description of the schema](https://github.com/wordpress/gutenberg/blob/trunk/packages/dom/src/dom/types.ts). ``` js schema = { span: { children: { '#text': {} } } }; ``` **Example: a custom content model** Suppose we want to match the following HTML snippet and turn it into some kind of custom post preview block. ``` html

The Post Title

Some great content.

``` We want to tell the editor to allow the inner `h2` and `p` elements. We do this by supplying the following schema. In this example we’re using the function form, which accepts an argument supplying `phrasingContentSchema` (as well as a boolean `isPaste` indicating if the transformation operation started with pasting text). The `phrasingContentSchema` is pre-defined to match HTML phrasing elements, such as `` and `^{` and ``. Anywhere we expect\
a `` component is a good place to allow phrasing content otherwise we’ll lose all text formatting on conversion.

``` js
schema = ({ phrasingContentSchema }) => ({
div: {
required: true,
attributes: [ 'data-post-id' ],
children: {
h2: { children: phrasingContentSchema },
p: { children: phrasingContentSchema }
}
}
})
```

When we successfully match this content every HTML attribute will be stripped away except for `data-post-id` and if we have other arrangements of HTML inside of a given `div` then it won’t match our transformer. Likewise we’d fail to match if we found an `` in there instead of an `
`.

Schemas are most-important when wanting to match HTML snippets containing non-phrasing content, such as `` with a ``. Without declaring the custom schema the editor will skip over these other constructions before attempting to run them through any block transforms.

### Shortcode

This type of transformations support the *from* direction, allowing blocks to be created from shortcodes. It’s applied as part of the `raw` transformation process.

A transformation of type `shortcode` is an object that takes the following parameters:

- **type** *(string)*: the value `shortcode`.
- **tag** *(string\|array)*: the shortcode tag or list of shortcode aliases this transform can work with.
- **transform** *(function, optional)*: a callback that receives the shortcode attributes as the first argument and the [WPShortcodeMatch](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-shortcode/#next) as the second. It should return a block object or an array of block objects. When this parameter is defined, it will take precedence over the `attributes` parameter.
- **attributes** *(object, optional)*: object representing where the block attributes should be sourced from, according to the attributes shape defined by the [block configuration object](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/). If a particular attribute contains a `shortcode` key, it should be a function that receives the shortcode attributes as the first arguments and the [WPShortcodeMatch](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-shortcode/#next) as second, and returns a value for the attribute that will be sourced in the block’s comment.
- **isMatch** *(function, optional)*: a callback that receives the shortcode attributes per the [Shortcode API](https://codex.wordpress.org/Shortcode_API) and should return a boolean. Returning `false` from this function will prevent the shortcode to be transformed into this block.
- **priority** *(number, optional)*: controls the priority with which a transform is applied, where a lower value will take precedence over higher values. This behaves much like a [WordPress hook](https://developer.wordpress.org/reference/#Hook_to_WordPress). Like hooks, the default priority is `10` when not otherwise set.

**Example: from shortcode to block using `transform`**

An existing shortcode can be transformed into its block counterpart using the `transform` method.

``` js
transforms: {
from: [
{
type: 'shortcode',
tag: 'video',
transform( { named: { src } } ) {
return createBlock( 'core/video', { src } );
},
// Prevent the shortcode to be converted
// into this block when it doesn't
// have the proper ID.
isMatch( { named: { id } } ) {
return id === 'my-id';
},
},
],
},
```

**Example: from shortcode to block using `attributes`**

An existing shortcode can be transformed into its block counterpart using the `attributes` parameters.

``` js
transforms: {
from: [
{
type: 'shortcode',
tag: 'youtube',
attributes: {
url: {
type: 'string',
source: 'attribute',
attribute: 'src',
selector: 'img',
},
align: {
type: 'string',
// The shortcode function will extract
// the shortcode atts into a value
// to be sourced in the block's comment.
shortcode: ( { named: { align = 'alignnone' } } ) => {
return align.replace( 'align', '' );
},
},
},
// Prevent the shortcode to be converted
// into this block when it doesn't
// have the proper ID.
isMatch( { named: { id } } ) {
return id === 'my-id';
},
},
]
},
```

**Example: shortcode with wrapped content to block with InnerBlocks**

Shortcodes that wrap inner content (e.g. `[example]Inner.[/example]`) can be transformed into a block with InnerBlocks by passing `match.shortcode.content` through [`rawHandler`](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-blocks/#rawhandler) inside `transform`.

``` js
transforms: {
from: [
{
type: 'shortcode',
tag: 'example',
transform( attrs, match ) {
const innerBlocks = rawHandler( {
HTML: match.shortcode.content || '',
} );
return createBlock(
'myplugin/example',
{ att1: attrs.named.att1 || '' },
innerBlocks
);
},
},
],
},
```

`rawHandler` recurses into the content, so nested shortcodes and HTML are converted to blocks the same way pasted content is.

## `ungroup` blocks

Via the optional `transforms` key of the block configuration, blocks can use the `ungroup` subkey to define the blocks that will replace the block being processed. These new blocks will usually be a subset of the existing inner blocks, but could also include new blocks.

If a block has an `ungroup` transform, it is eligible for ungrouping, without the requirement of being the default grouping block. The UI used to ungroup a block with this API is the same as the one used for the default grouping block. In order for the Ungroup button to be displayed, we must have a single grouping block selected, which also contains some inner blocks.

**ungroup** is a callback function that receives the attributes and inner blocks of the block being processed. It should return an array of block objects.

Example:

``` js
export const settings = {
title: 'My grouping Block Title',
description: 'My grouping block description',
/* ... */
transforms: {
ungroup: ( attributes, innerBlocks ) =>
innerBlocks.flatMap( ( innerBlock ) => innerBlock.innerBlocks ),
},
};
```

# Variations

The Block Variations API allows you to define multiple versions (variations) of a block. A block variation differs from the original block by a set of initial attributes or inner blocks. When you insert the block variation into the Editor, these attributes and/or inner blocks are applied.

Variations are an excellent way to create iterations of existing blocks without building entirely new blocks from scratch.

To better understand this API, consider the Embed block. This block contains numerous variations for each type of embeddable content (WordPress, Youtube, etc.). Each Embed block variation shares the same underlying functionality for editing, saving, and so on. Besides the name and descriptive information, the main difference is the `providerNameSlug` attribute. Below is a simplified example of the variations in the Embed block. View the [source code](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/embed/variations.js) for the complete specification.

``` js
variations: [
{
name: 'wordpress',
title: 'WordPress',
description: __( 'Embed a WordPress post.' ),
attributes: { providerNameSlug: 'wordpress' },
},
{
name: 'youtube',
title: 'YouTube',
description: __( 'Embed a YouTube video.' ),
attributes: { providerNameSlug: 'youtube' },
},
],
```

## Defining a block variation

A block variation is defined by an object that can contain the following fields:

- `name` (type `string`) – A unique and machine-readable name.
- `title` (optional, type `string`) – A human-readable variation title.
- `description` (optional, type `string`) – A human-readable variation description.
- `category` (optional, type `string`) – A category classification used in search interfaces to arrange block types by category.
- `keywords` (optional, type `string[]`) – An array of terms (which can be translated) that help users discover the variation while searching.
- `icon` (optional, type `string` \| `Object`) – An icon helping to visualize the variation. It can have the same shape as the block type.
- `attributes` (optional, type `Object`) – Values that override block attributes.
- `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
- `innerContent` (optional, type `Array`) – Static HTML fragments interleaved with inner blocks, where `null` entries mark the positions of the inner blocks within the static markup. Only applies to the Custom HTML block.
- `example` (optional, type `Object`) – Provides structured data for the block preview. Set to `undefined` to disable the preview. See the [Block Registration API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#example-optional) for more details.
- `scope` (optional, type `WPBlockVariationScope[]`) – Defaults to `block` and `inserter`. The list of scopes where the variation is applicable. Available options include:
- `block` – Used by blocks to filter specific block variations. `Columns` and `Query` blocks have such variations, which are passed to the [experimental BlockVariationPicker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md) component. This component handles displaying the variations and allows users to choose one of them.
- `inserter` – Block variation is shown on the inserter.
- `transform` – Block variation is shown in the component for variation transformations.
- `isDefault` (optional, type `boolean`) – Defaults to `false`. Indicates whether the current variation is the default one (details below).
- `isActive` (optional, type `Function|string[]`) – A function or an array of block attributes that is used to determine if the variation is active when the block is selected. The function accepts `blockAttributes` and `variationAttributes` (details below).
- `shortcut` (optional, type `Object`) – A keyboard shortcut that applies the variation to the selected block (details below).

You can technically create a block variation without a unique `name`, but this is **not** recommended. A unique `name` allows the Editor to differentiate between your variation and others that may exist. It also allows your variation to be unregistered as needed and has implications for the `isDefault` settings (details below).

## Creating a block variation

Block variations can be declared during a block’s registration by providing the `variations` key with a proper array of variation objects, as shown in the example above. See the [Block Registration API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/) for more details.

To create a variation for an existing block, such as a Core block, use `wp.blocks.registerBlockVariation()`. This function accepts the name of the block and the object defining the variation.

``` js
wp.blocks.registerBlockVariation( 'core/embed', {
name: 'custom-embed',
attributes: { providerNameSlug: 'custom' },
} );
```

## Registering block variations in PHP

Block variations can also be registered from PHP using the `get_block_type_variations` filter hook. This approach is particularly useful when you need to dynamically generate variations based on registered post types, taxonomies, or other WordPress data.

Here’s an example of how to register a custom variation for the `core/image` block:

``` php
function my_custom_image_variation( $variations, $block_type ) {
// Only modify variations for the image block
if ( 'core/image' !== $block_type->name ) {
return $variations;
}

// Add a custom variation
$variations[] = array(
'name' => 'wide-image',
'title' => __( 'Wide image', 'textdomain' ),
'description' => __( 'A wide image', 'textdomain' ),
'scope' => array( 'inserter' ),
'isDefault' => false,
'attributes' => array(
'align' => 'wide', // Identifies the link type as custom
),
);

return $variations;
}
add_filter( 'get_block_type_variations', 'my_custom_image_variation', 10, 2 );
```

The `get_block_type_variations` filter is called when variations are requested for a block type. It receives two parameters:\
– `$variations`: An array of currently registered variations for the block type\
– `$block_type`: The full block type object

Note that variations registered through PHP will be merged with any variations registered through JavaScript using `registerBlockVariation()`.

Check the [How to register block variations with PHP](https://developer.wordpress.org/news/2024/03/how-to-register-block-variations-with-php/) blog post for more info about this

## Removing a block variation

Block variations can also be easily removed. To do so, use `wp.blocks.unregisterBlockVariation()`. This function accepts the name of the block and the `name` of the variation that should be unregistered.

``` js
wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' );
```

## Block variations versus block styles

The main difference between block styles and block variations is that a block style just applies a CSS class to the block, so it can be styled in an alternative way. See the [Block Styles API](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/) for more details.

If you want to apply initial attributes or inner blocks, this falls into block variation territory. It’s also possible to override the default block style using the `className` attribute when defining a block variation.

``` js
variations: [
{
name: 'blue',
title: __( 'Blue Quote' ),
isDefault: true,
attributes: {
color: 'blue',
className: 'is-style-blue-quote'
},
icon: 'format-quote',
isActive: ( blockAttributes, variationAttributes ) =>
blockAttributes.color === variationAttributes.color
},
],
```

## Using `isDefault`

By default, all variations will show up in the Inserter in addition to the original block type item. However, setting the `isDefault` flag for any variations listed will override the regular block type in the Inserter. This is a great tool for curating the Editor experience to your specific needs.

For example, if you want Media & Text block to display the image on the right by default, you could create a variation like this:

``` js
wp.blocks.registerBlockVariation( 'core/media-text', {
name: 'media-text-media-right',
title: __( 'Media & Text' ),
isDefault: true,
attributes: {
mediaPosition: 'right',
},
} );
```

### Caveats to using `isDefault`

While `isDefault` works great when overriding a block without existing variations, you may run into issues when other variations exist.

If another variation for the same block uses `isDefault`, your variation will not necessarily become the default. The Editor respects the first registered variation with `isDefault`, which might not be yours.

The solution is to unregister the other variation before registering your variation with `isDefault`. This caveat reinforces the recommendation always to provide variations with a unique `name`. Otherwise, the variation cannot be unregistered.

## Using `isActive`

While the `isActive` property is optional, it’s recommended. This API is used by the block editor to check which variation is active, and display the correct variation’s title, icon and description when an instance of the variation is selected in the editor.

If `isActive` is not set, the Editor cannot distinguish between an instance of the original block and your variation, so the original block information will be displayed.

The property can be set to either an array of strings (`string[]`), or a function. It is recommended to use the string array version whenever possible.

The `string[]` version is used to declare which of the block instance’s attributes should be compared to the given variation’s. Each attribute will be checked and the variation will be active if all of them match.

As an example, in the core Embed block, the `providerNameSlug` attribute is used to determine the embed provider (e.g. ‘youtube’ or ‘twitter’). The variations may be declared like this:

``` js
const variations = [
{
name: 'twitter',
title: 'Twitter',
icon: embedTwitterIcon,
keywords: [ 'tweet', __( 'social' ) ],
description: __( 'Embed a tweet.' ),
patterns: [ /^https?:\/\/(www\.)?twitter\.com\/.+/i ],
attributes: { providerNameSlug: 'twitter', responsive: true },
},
{
name: 'youtube',
title: 'YouTube',
icon: embedYouTubeIcon,
keywords: [ __( 'music' ), __( 'video' ) ],
description: __( 'Embed a YouTube video.' ),
patterns: [
/^https?:\/\/((m|www)\.)?youtube\.com\/.+/i,
/^https?:\/\/youtu\.be\/.+/i,
],
attributes: { providerNameSlug: 'youtube', responsive: true },
},
// ...
];
```

The `isActive` property would then look like this:

``` js
isActive: [ 'providerNameSlug' ];
```

This will cause the block instance value for `providerNameSlug` to be compared to the value declared in the variation’s declaration (the values in the code snippet above) to determine which embed variation is active.

Nested object paths are also supported since WordPress `6.6.0`. For example, consider a block variation that has a `query` object as an attribute. It is possible to determine if the variation is active solely based on that object’s `postType` property (while ignoring all its other properties):

``` js
isActive: [ 'query.postType' ];
```

The function version of this property accepts a block instance’s `blockAttributes` as the first argument, and the `variationAttributes` declared for a variation as the second argument. These arguments can be used to determine if a variation is active by comparing them and returning a `true` or `false` (indicating whether this variation is inactive for this block instance).

Using the same example for the embed block, the function version would look like this:

``` js
isActive: ( blockAttributes, variationAttributes ) =>
blockAttributes.providerNameSlug === variationAttributes.providerNameSlug,
```

### Specificity of `isActive` matches

*Note: Improved handling since WordPress `6.6.0`.*

If there are multiple variations whose `isActive` check matches a given block instance, and all of them are string arrays, then the variation with the highest *specificity* will be chosen. Consider the following example:

``` js
wp.blocks.registerBlockVariation( 'core/paragraph', {
name: 'paragraph-red',
title: 'Red Paragraph',
attributes: {
textColor: 'vivid-red',
},
isActive: [ 'textColor' ],
} );

wp.blocks.registerBlockVariation( 'core/paragraph', {
name: 'paragraph-red-grey',
title: 'Red/Grey Paragraph',
attributes: {
textColor: 'vivid-red',
backgroundColor: 'cyan-bluish-gray',
},
isActive: [ 'textColor', 'backgroundColor' ],
} );
```

If a block instance has attributes `textColor: vivid-red` and `backgroundColor: cyan-bluish-gray`, both variations’ `isActive` criterion will match that block instance. In this case, the more *specific* match will be determined to be the active variation, where specificity is calculated as the length of each `isActive` array. This means that the `Red/Grey Paragraph` will be shown as the active variation.

Note that specificity cannot be determined for a matching variation if its `isActive` property is a function rather than a `string[]`. In this case, the first matching variation will be determined to be the active variation. For this reason, it is generally recommended to use a `string[]` rather than a `function` for the `isActive` property.

## Using `shortcut`

A variation can declare a keyboard shortcut that applies it to the selected block. The shortcut is registered with the editor’s keyboard shortcuts store and listed in the keyboard shortcuts help modal.

The `shortcut` object takes the following parameters:

- `name` (type `string`) – A unique and machine-readable shortcut name, e.g. `core/block-editor/transform-to-heading-2`.
- `description` (type `string`) – A translated description, displayed in the keyboard shortcuts help modal.
- `keyCombination` (type `Object`) – The key combination that triggers the shortcut, as a `character` and an optional `modifier` (one of the modifiers supported by the [`wp-keycodes` package](https://developer.wordpress.org/block-editor/reference-guide/packages/packages-keycodes/), e.g. `access` or `primary`).
- `aliases` (optional, type `Object[]`) – Alternative key combinations that trigger the same shortcut.

For example, the core Heading block gives each of its level variations a shortcut:

``` js
wp.blocks.registerBlockVariation( 'core/heading', {
name: 'h2',
title: 'Heading 2',
attributes: { level: 2 },
isActive: ( blockAttributes ) => blockAttributes.level === 2,
shortcut: {
name: 'core/block-editor/transform-to-heading-2',
description: __( 'Transform the selected block into a heading 2.' ),
keyCombination: { modifier: 'access', character: '2' },
},
} );
```

The shortcut only applies to blocks that are already of the variation’s own block type: it sets the variation’s `attributes` on the selected block, and does nothing when `isActive` reports the variation as already active. In the example above, that is what lets the shortcut change the level of an existing Heading block.

To reach the variation from a *different* block type, declare the same shortcut on a [block transform](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-transforms/#keyboard-shortcuts) that produces this block, giving it the same `name` and a `variationName` pointing back at the variation. The Heading block does both, which is why Alt+Shift+2 turns a Paragraph into an H2 as well as changing an existing heading’s level. Declaring one shortcut in several places is expected, as long as every declaration agrees on the key combination and description; the two can never both apply to the same selection.

Shortcuts only apply to blocks that are fully editable, and are ignored for blocks in a restricted editing mode such as content-only editing.

Key combinations are matched globally, so a combination already claimed by another block or by the editor itself will not reliably reach your variation. In development builds a warning is logged when two blocks declare the same combination.

# Styles

Block Styles allow alternative styles to be applied to existing blocks. They work by adding a className to the block’s wrapper. This className can be used to provide an alternative styling for the block if the block style is selected. See the [Use styles and stylesheets](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/applying-styles-with-stylesheets/) for a full example on how to apply styles to a block.

*Example:*

``` js
wp.blocks.registerBlockStyle( 'core/quote', {
name: 'fancy-quote',
label: 'Fancy Quote',
} );
```

The example above registers a block style named `fancy-quote` to the `core/quote` block. When the user selects this block style from the styles selector, an `is-style-fancy-quote` className will be added to the block’s wrapper.

By adding `isDefault: true` you can mark the registered block style as the one that is recognized as active when no custom class name is provided. It also means that there will be no custom class name added to the HTML output for the style that is marked as default.

To remove a block style use `wp.blocks.unregisterBlockStyle()`.

*Example:*

``` js
wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
```

The above removes the block style named `large` from the `core/quote` block.

**Important:** When unregistering a block style, there can be a [race condition](https://en.wikipedia.org/wiki/Race_condition) on which code runs first: registering the style, or unregistering the style. You want your unregister code to run last. The way to do that is specify the component that is registering the style as a dependency, in this case `wp-edit-post`. Additionally, using `wp.domReady()` ensures the unregister code runs once the dom is loaded.

Enqueue your JavaScript with the following PHP code:

``` php
function myguten_enqueue() {
wp_enqueue_script(
'myguten-script',
plugins_url( 'myguten.js', __FILE__ ),
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
filemtime( plugin_dir_path( __FILE__ ) . '/myguten.js' )
);
}
add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
```

The JavaScript code in `myguten.js`:

``` js
wp.domReady( function () {
wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
} );
```

## Server-side registration helper

While the samples provided do allow full control of block styles, they do require a considerable amount of code.

To simplify the process of registering and unregistering block styles, two server-side functions are also available: `register_block_style`, and `unregister_block_style`.

### register_block_style

The `register_block_style` function receives the name of the block as the first argument and an array describing properties of the style as the second argument.

The properties of the style array must include `name` and `label`:

- `name`: The identifier of the style used to compute a CSS class.
- `label`: A human-readable label for the style.

Besides the two mandatory properties, the styles properties array should also include an `inline_style` or a `style_handle` or a `style_data`property:

- `inline_style`: Contains inline CSS code that registers the CSS class required for the style.
- `style_handle`: Contains the handle to an already registered style that should be enqueued in places where block styles are needed.
- `style_data`: Contains a theme.json-like notation in an array of style properties.

It is also possible to set the `is_default` property to `true` to mark one of the block styles as the default one, should one be missing.

The following code sample registers a style for the quote block named “Blue Quote”, and provides an inline style that makes quote blocks with the “Blue Quote” style have blue color:

``` php
register_block_style(
'core/quote',
array(
'name' => 'blue-quote',
'label' => __( 'Blue Quote', 'textdomain' ),
'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
)
);
```

Alternatively, if a stylesheet was already registered which contains the CSS for the block style, it is possible to just pass the stylesheet’s handle so `register_block_style` function will make sure it is enqueued.

The following code sample provides an example of this use case:

``` php
wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' );

// ...

register_block_style(
'core/quote',
array(
'name' => 'fancy-quote',
'label' => __( 'Fancy Quote', 'textdomain' ),
'style_handle' => 'myguten-style',
)
);
```

Another way is using the `style_data`property, as in below code example. It adds a block style to the image block with an orange border and slightly rounded corners.

``` php
register_block_style(
array( 'core/image' ),
array(
'name' => 'orange-border',
'label' => __( 'Orange Border', 'pauli' ),
'style_data'=> array(
'border' => array(
'color' => '#f5bc42',
'style' => 'solid',
'width' => '4px',
'radius' => '15px'
)
)
)
);
```

Using the `style_data` property empowers the user to change it with the Global Styles UI via the **Editor \> Styles**. The `style_data`property was added in WordPress 6.6.

More information via WordPress 6.6 Dev Note: [Section Styles](https://make.wordpress.org/core/2024/06/24/section-styles/).\
Also on the WordPress Developer Blog: [Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6](https://developer.wordpress.org/news/2024/06/styling-sections-nested-elements-and-more-with-block-style-variations-in-wordpress-6-6/)

### unregister_block_style

`unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_style`.

The function’s first argument is the registered name of the block, and the name of the style as the second argument.

The following code sample unregisters the style named ‘fancy-quote’ from the quote block:

``` php
unregister_block_style( 'core/quote', 'fancy-quote' );
```

**Important:** The function `unregister_block_style` only unregisters styles that were registered on the server using `register_block_style`. The function does not unregister a style registered using client-side code.

# Selectors

Block Selectors is the API that allows blocks to customize the CSS selector used\
when their styles are generated.

A block may customize its CSS selectors at three levels: root, feature, and\
subfeature.

## Root selector

The root selector is the block’s primary CSS selector.

All blocks require a primary CSS selector for their style declarations to be\
included under. If one is not provided through the Block Selectors API, a\
default is generated in the form of `.wp-block-`.

### Example

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector"
}
}
```

## Feature selectors

Feature selectors relate to styles for a block support, e.g. border, color,\
typography, etc.

A block may wish to apply the styles for specific features to different\
elements within a block. An example might be using colors on the block’s wrapper\
but applying the typography styles to an inner heading only.

### Example

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector",
"color": ".my-custom-block-selector",
"typography": ".my-custom-block-selector > h2"
}
}
```

## Subfeature selectors

These selectors relate to individual styles provided by a block support e.g.\
`background-color`

A subfeature can have styles generated under its own unique selector. This is\
especially useful where one block support subfeature can’t be applied to the\
same element as the support’s other subfeatures.

A great example of this is `text-decoration`. Web browsers render this style\
differently, making it difficult to override if added to a wrapper element. By\
assigning `text-decoration` a custom selector, its style can target only the\
elements to which it should be applied.

### Example

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector",
"color": ".my-custom-block-selector",
"typography": {
"root": ".my-custom-block-selector > h2",
"text-decoration": ".my-custom-block-selector > h2 span"
}
}
}
```

## Custom CSS selector

The `css` selector controls which selector is used when generating a block’s\
custom CSS rules set via Global Styles. This maps to the\
`styles.blocks..css` property in theme.json.

If not set, the block’s root selector is used.

### Examples

As a string:

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector",
"css": ".my-custom-block-selector > .inner-wrapper"
}
}
```

As an object with a `root` key:

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector",
"css": {
"root": ".my-custom-block-selector > .inner-wrapper"
}
}
}
```

## Shorthand

Rather than specify a CSS selector for every subfeature, you can set a single\
selector as a string value for the relevant feature. This is the approach\
demonstrated for the `color` feature in the earlier examples above.

## Fallbacks

A selector that hasn’t been configured for a specific feature will fall back to\
the block’s root selector. Similarly, if a subfeature hasn’t had a custom\
selector set, it will fall back to its parent feature’s selector and, if unavailable, fall back further to the block’s root selector.

Rather than repeating selectors for multiple subfeatures, you can set the\
common selector as the parent feature’s `root` selector and only define the\
unique selectors for the subfeatures that differ.

### Example

``` json
{
...
"selectors": {
"root": ".my-custom-block-selector",
"color": {
"text": ".my-custom-block-selector p"
},
"typography": {
"root": ".my-custom-block-selector > h2",
"text-decoration": ".my-custom-block-selector > h2 span"
}
}
}
```

The `color.background-color` subfeature isn’t explicitly set in the above\
example. As the `color` feature also doesn’t define a `root` selector,\
`color.background-color` would be included under the block’s primary root\
selector, `.my-custom-block-selector`.

For a subfeature such as `typography.font-size`, it would fallback to its parent\
feature’s selector given that is present, i.e. `.my-custom-block-selector > h2`.

# Bindings

Block Bindings API is only available for WordPress 6.5 and above.

The Block Bindings API lets you “bind” dynamic data to the block’s attributes, which are then reflected in the final HTML markup that is output to the browser on the front end.

An example could be connecting an Image block `url` attribute to a function that returns random images from an external API.

``` html

```

## Compatible blocks and their attributes

Right now, not all block attributes are compatible with block bindings. There is some ongoing effort to increase this compatibility, but for now, this is the default list:

| Supported Blocks | Supported Attributes |
|-------------------------|------------------------------|
| core/image | id, url, title, alt, caption |
| core/heading | content |
| core/paragraph | content |
| core/button | url, text, linkTarget, rel |
| core/navigation-link | url |
| core/navigation-submenu | url |
| core/post-date | datetime |

## Core Sources

WordPress includes several built-in block bindings sources that you can use without any custom registration:

- `core/post-meta`
- `core/post-data`
- `core/term-data`
- `core/pattern-overrides`

### core/post-meta

The `core/post-meta` source allows you to bind block attributes to post meta fields.

**Requirements:**

- Post meta must be registered with `show_in_rest => true`
- Post meta keys cannot start with an underscore (protected keys are not accessible)

**Example usage:**

First, register your post meta:

``` php
register_meta(
'post',
'my_custom_field',
array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
)
);
```

Then bind it to a block attribute:

``` html

Fallback content

```

### core/post-data

***Note:** Since WordPress 6.9.*

The `core/post-data` source provides access to post data fields.

**Available fields:**

- `date` – The post publication date
- `modified` – The post last modified date
- `link` – The post permalink

**Example usage:**

``` html

Fallback content

```

### core/term-data

***Note:** Since WordPress 6.9.*

The `core/term-data` source provides access to taxonomy term data fields when term context is available. It requires `termId` and `taxonomy` to be available from block context to function properly.

#### Available Fields

| Field | Description | Example Output |
|----|----|----|
| `id` | Term ID | `123` |
| `name` | Term name | `Category Name` |
| `link` | URL to term archive | \`https://example.com/category/news\` |
| `slug` | URL-friendly slug | `category-slug` |
| `description` | Term description | `A description of the category` |
| `parent` | Parent term ID (hierarchical taxonomies) | `0` |
| `count` | Number of posts in this term | `5` |

#### Example Usage

**Display term names in a list:**

``` html

Category Name

```

**Create linked term archives:**

``` html

Tag Name

```

#### Context Requirements

The [`core/term-data`](https://github.com/WordPress/gutenberg/tree/trunk/packages/editor/src/bindings/term-data.js) source works in these contexts:

1. **Any block providing term context** – Built-in blocks like [`core/term-template`](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/term-template), or custom blocks that provide `termId` and `taxonomy` via block context
2. **Navigation Blocks** – Special backwards compatibility handling for `core/navigation-link` and `core/navigation-submenu` (these read from block attributes instead of context)

### core/pattern-overrides

The `core/pattern-overrides` source enables pattern instances to have their content overridden on a per-instance basis. This is particularly useful for synced patterns where you want to allow specific blocks to be customized while keeping the rest of the pattern synchronized .

**How it works:**

- Pattern blocks can define which attributes are overridable using `metadata.bindings`
- Each pattern instance stores its override values in the `content` attribute
- The binding connects the block attribute to the override value using the block’s `metadata.name` as a key
- The context structure follows: `pattern/overrides → {block_name} → {attribute_name}`

**Example usage:**

In the pattern definition, mark blocks as overridable:

``` html

Default heading text

```

When the pattern is instantiated, users can override the content for that specific instance:

``` html

```

In this example:

- **`custom-heading`** is a unique identifier for the `core/paragraph` block within the `core/pattern-overrides` system.
- It acts as a key in the overrides context structure: `pattern/overrides → custom-heading → content`.
- This identifier allows multiple blocks of the same type (e.g., `core/paragraph`) within a pattern to have distinct, per-instance attribute overrides using `metadata.name`.

For instance, `"custom-heading"` links the specific paragraph block’s `content` attribute to its override value (`"My custom heading text"`) for a particular pattern instance.

### Extending supported attributes

***Note:** Since WordPress 6.9.*

Developers can extend the list of supported attributes using the `block_bindings_supported_attributes` filter. This filter allows adding support for additional block attributes.

There are two filters available:

- `block_bindings_supported_attributes`: A general filter that receives the supported attributes array and the block type name.
- `block_bindings_supported_attributes_{$block_type}`: A dynamic filter specific to a block type (e.g., `block_bindings_supported_attributes_core/image`).

Example of adding support for the `linkDestination` attribute on the Image block (attributes already supported by default are listed in the [Compatible blocks](#compatible-blocks-and-their-attributes) table above):

``` php
add_filter(
'block_bindings_supported_attributes_core/image',
function ( $supported_attributes ) {
$supported_attributes[] = 'linkDestination';
return $supported_attributes;
}
);
```

Example of adding support for a custom block:

``` php
add_filter(
'block_bindings_supported_attributes_my-plugin/my-block',
function ( $supported_attributes ) {
$supported_attributes[] = 'title';
$supported_attributes[] = 'description';
return $supported_attributes;
}
);
```

This filter also affects which blocks and attributes are available for Pattern Overrides, as both features share the same underlying supported attributes configuration.

## Registering a custom source

Registering a source requires defining at least `name`, a `label` and a `callback` function that gets a value from the source and passes it back to a block attribute.

Once a source is registered, any supporting block’s `metadata.bindings` attribute can be configured to read a value from that source.

Registration can be done on the server via PHP or in the editor via JavaScript, and both can coexist.

The label defined in server registration will be overridden by the label defined in the editor.

### Server registration

Server registration allows applying a callback that will be executed on the frontend for the bound attribute.

The function to register a custom source is `register_block_bindings_source($name, $args)`:

- `name`: `string` that sets the unique ID for the custom source.
- `args`: `array` that contains:
- `label`: `string` with the human-readable name of the custom source.
- `uses_context`: `array` with the block context that is passed to the callback (optional).
- `get_value_callback`: `function` that will run on the bound block’s render function. It accepts three arguments: `source_args`, `block_instance` and `attribute_name`. This value can be overridden with the filter `block_bindings_source_value`.

Note that `register_block_bindings_source()` should be called from a handler attached to the `init` hook.

Here is an example:

``` php
add_action(
'init',
function () {
register_block_bindings_source(
'wpmovies/visualization-date',
array(
'label' => __( 'Visualization Date', 'custom-bindings' ),
'get_value_callback' => function ( array $source_args, $block_instance ) {
$post_id = $block_instance->context['postId'];
if ( isset( $source_args['key'] ) ) {
return get_post_meta( $post_id, $source_args['key'], true );
}
},
'uses_context' => array( 'postId' ),
)
);
}
);
```

This example needs a `post_meta` registered, and, also, a filter can be used to return a default `$visualization_date` value, which will be shown in the next heading.

``` php
add_action(
'init',
function () {
register_meta(
'post',
'wp_movies_visualization_date',
array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'label' => __( 'Movie visualization date', 'custom-bindings' ),
)
);
}
);
```

**Note:** Post meta keys that begin with an underscore (e.g. \`\_example_key\`) are protected and cannot be used with Block Bindings. Additionally, post meta must be registered with \`show_in_rest = true\` to be available through the Block Bindings API.

#### Block bindings source value filter

***Note:** Since WordPress 6.7.*

The value returned by `get_value_callback` can be modified with the `block_bindings_source_value` filter.\
The filter has the following parameters:

- `value`: The value to be filtered.
- `name`: The name of the source.
- `source_args`: `array` containing source arguments.
- `block_instance`: The block instance object.
- `attribute_name`: The name of the attribute.

Example:

``` php
function wpmovies_format_visualization_date( $value, $name ) {
// Prevent the filter to be applied to other sources.
if ( $name !== 'wpmovies/visualization-date' ) {
return $value;
}
if ( ! $value ) {
return date( 'm/d/Y' );
}
return date( 'm/d/Y', strtotime( $value ) );
}

add_filter( 'block_bindings_source_value', 'wpmovies_format_visualization_date', 10, 2 );
```

#### Server registration Core examples

There are a few examples in Core that can be used as reference.

- Post Meta. [Source code](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/post-meta.php)
- Post Data. [Source code](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/post-data.php)
- Term Data. [Source code](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/term-data.php)
- Pattern overrides. [Source code](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/pattern-overrides.php)
- Twenty Twenty-Five theme. [Source code](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-content/themes/twentytwentyfive/functions.php)

### Editor registration

***Note:** Since WordPress 6.7.*

Editor registration on the client allows defining what the bound block will do when the value is retrieved or when the value is edited.

The function to register a custom source is `registerBlockBindingsSource( args )`:

- `args`: `object` with the following structure:
- `name`: `string` with the unique and machine-readable name.
- `label`: `string` with the human readable name of the custom source. In case it was defined already on the server, the server label will be overridden by this one, in that case, it is not recommended to be defined here. (optional)
- `usesContext`: `array` with the block context that the custom source may need. In case it was defined already on the server, it should not be defined here. (optional)
- `getValues`: `function` that retrieves the values from the source. (optional)
- `setValues`: `function` that allows updating the values connected to the source. (optional)
- `canUserEditValue`: `function` to determine if the user can edit the value. The user won’t be able to edit by default. (optional)
- `getFieldsList`: `function` that returns available fields for the UI dropdown selector. (*Since WordPress 6.9*) (optional)

This example will show a custom post meta date in the editor and, if it doesn’t exist, it will show today’s date. The user can edit the value of the date. (Caution: This example does not format the user input as a date—it’s only for educational purposes.)

``` js
import { registerBlockBindingsSource } from '@wordpress/blocks';
import { __ } from '@wordpress/i18n';
import { store as coreDataStore } from '@wordpress/core-data';

registerBlockBindingsSource( {
name: 'wpmovies/visualization-date',
label: __( 'Visualization Date', 'custom-bindings' ), // We can skip the label, as it was already defined in the server in the previous example.
usesContext: [ 'postType' ], // We can skip postId, as it was already defined in the server in the previous example.
getValues( { select, context } ) {
let wpMoviesVisualizationDate;
const { getEditedEntityRecord } = select( coreDataStore );
if ( context?.postType && context?.postId ) {
wpMoviesVisualizationDate = getEditedEntityRecord(
'postType',
context?.postType,
context?.postId
).meta?.wp_movies_visualization_date;
}
if ( wpMoviesVisualizationDate ) {
return {
content: wpMoviesVisualizationDate,
};
}

return {
content: new Date().toLocaleDateString( 'en-US' ),
};
},
setValues( { select, dispatch, context, bindings } ) {
dispatch( coreDataStore ).editEntityRecord(
'postType',
context?.postType,
context?.postId,
{
meta: {
wp_movies_visualization_date: bindings?.content?.newValue,
},
}
);
},
canUserEditValue( { select, context } ) {
return true;
},
} );
```

#### getValues

The `getValues` function retrieves the value from the source on block loading. It receives an `object` as an argument with the following properties:

- `bindings` returns the bindings object of the specific source. It must have the attributes as a key, and the value can be a `string` or an `object` with arguments.
- `clientId` returns a `string` with the current block client ID.
- `context` returns an `object` of the current block context, defined in the `usesContext` property. [More about block context.](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/).
- `select` returns an `object` of a given store’s selectors. [More info in their docs.](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#select).

The function must return an `object` with this structure:\
`{ 'block attribute' : value }`

#### setValues

The `setValues` function updates all the values of the source of the block bound. It receives an `object` as an argument with the following properties:

- `bindings` returns the bindings object of the specific source. It must have the attributes as a key, and the value can be a `string` or an `object` with arguments. This object contains a `newValue` property with the user’s input.
- `clientId` returns a `string` with the current block client ID.
- `context` returns an `object` of the current block context, defined in the `usesContext` property. [More about block context.](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/).
- `dispatch` returns an `object` of the store’s action creators. [More about dispatch](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#dispatch).
- `select` returns an `object` of a given store’s selectors. [More info in their docs.](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#select).

#### getFieldsList

***Note:** Since WordPress 6.9.*

The `getFieldsList` function enables custom sources to appear in the Block Bindings UI dropdown selector. When a user selects an option from the dropdown, the source is automatically bound to the block attribute with the corresponding `args` from the selected field. This function must return an array of field objects that define the available binding options.

Each field object in the array should have the following properties:

- `label`: `string` that defines the label shown in the dropdown selector. Defaults to the source label if not provided.
- `type`: `string` that defines the attribute value type. It must match the attribute type it binds to; otherwise, it won’t appear in the UI. For example, an `id` attribute that accepts only numbers should only display fields that return numeric values.
- `args`: `object` that defines the source arguments that are applied when a user selects the field from the dropdown.

Example:

``` js
registerBlockBindingsSource( {
name: 'my-plugin/custom-fields',
label: 'Custom Fields',
getFieldsList() {
return [
{
label: 'Author Name',
type: 'string',
args: {
field: 'author_name',
},
},
{
label: 'Publication Year',
type: 'string',
args: {
field: 'publication_year',
},
},
{
label: 'Page Count',
type: 'number',
args: {
field: 'page_count',
},
},
];
},
getValues( { bindings } ) {
// Implementation to retrieve values based on args.field
},
} );
```

With this implementation, users will see “Author Name”, “Publication Year”, and “Page Count” as options in the Block Bindings UI dropdown when binding block attributes to your custom source.

Check the [Editor Bindings](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/editor-bindings) example from the [Block Development Examples](https://github.com/WordPress/block-development-examples/) repo

#### Editor registration Core examples

There are a few examples in Core that can be used as reference.

- Post Meta. [Source code](https://github.com/WordPress/gutenberg/blob/5afd6c27bfba2be2e06b502257753fbfff1ae9f0/packages/editor/src/bindings/post-meta.js#L74-L146)
- Pattern overrides. [Source code](https://github.com/WordPress/gutenberg/blob/5afd6c27bfba2be2e06b502257753fbfff1ae9f0/packages/editor/src/bindings/pattern-overrides.js#L8-L100)

## Unregistering a source

***Note:** Since WordPress 6.7.*

`unregisterBlockBindingsSource` unregisters a block bindings source by providing its name.

``` js
import { unregisterBlockBindingsSource } from '@wordpress/blocks';

unregisterBlockBindingsSource( 'plugin/my-custom-source' );
```

## Getting all sources

***Note:** Since WordPress 6.7.*

`getBlockBindingsSources` returns all registered block bindings sources.

``` js
import { getBlockBindingsSources } from '@wordpress/blocks';

const registeredSources = getBlockBindingsSources();
```

## Getting one specific source

***Note:** Since WordPress 6.7.*

`getBlockBindingsSource` return a specific block bindings source by its name.

``` js
import { getBlockBindingsSource } from '@wordpress/blocks';

const blockBindingsSource = getBlockBindingsSource( 'plugin/my-custom-source' );
```

## Block Bindings Utils

***Note:** Since WordPress 6.7.*

UseBlockBindingUtils is a hook with two helpers that allows developers to edit the `metadata.bindings` attribute easily.

It accepts a `clientId` string as a parameter, if it is not set, the function will use the current block client ID from the context.

Example:

``` js
import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { updateBlockBindings } = useBlockBindingsUtils('my-block-client-id-12345');
...
```

### updateBlockBindings

`updateBlockBindings` works similarly to `updateBlockAttributes`, and can be used to create, update, or remove specific connections.

``` js
import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { updateBlockBindings } = useBlockBindingsUtils();

function updateBlockBindingsURLSource( url ) {
updateBlockBindings( {
url: {
source: 'myplugin/new-source',
},
} );
}

// Remove binding from url attribute.
function removeBlockBindingsURLSource() {
updateBlockBindings( { url: undefined } );
}
```

### removeAllBlockBindings

`removeAllBlockBindings` will remove all existing connections in a block by removing the `metadata.bindings` attribute.

``` js
import { useBlockBindingsUtils } from '@wordpress/block-editor';

const { removeAllBlockBindings } = useBlockBindingsUtils();

function clearBlockBindings() {
removeAllBlockBindings();
}
```

# Block Filters

WordPress exposes several APIs that allow you to modify the behavior of existing blocks.

## Registration

Blocks in WordPress are typically registered on both the server and client side using `block.json` metadata. You can use the following filters to modify or extend block settings during their registration on the server with PHP and on the client with JavaScript. To learn more, refer to the [block registration](https://developer.wordpress.org/block-editor/getting-started/fundamentals/registration-of-a-block/) guide.

### `block_type_metadata`

Filters the raw metadata loaded from the `block.json` file when registering a block type on the server with PHP. It allows modifications to be applied before the metadata gets processed.

The callback function for this filter receives one parameter:

- `$metadata` (`array`): Metadata loaded from `block.json` for registering a block type.

The following example sets the `apiVersion` of all blocks to `2`.

``` php
function example_filter_metadata_registration( $metadata ) {
$metadata['apiVersion'] = 2;
return $metadata;
};
add_filter( 'block_type_metadata', 'example_filter_metadata_registration' );
```

Here’s a more robust example that disables background color and gradient support for Heading blocks. The `block_type_metadata` filter is excellent for [curating the Editor experience](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/).

``` php
function example_disable_heading_background_color_and_gradients( $metadata ) {

// Only apply the filter to Heading blocks.
if ( ! isset( $metadata['name'] ) || 'core/heading' !== $metadata['name'] ) {
return $metadata;
}

// Check if 'supports' key exists.
if ( isset( $metadata['supports'] ) && isset( $metadata['supports']['color'] ) ) {

// Remove Background color and Gradients support.
$metadata['supports']['color']['background'] = false;
$metadata['supports']['color']['gradients'] = false;
}

return $metadata;
}
add_filter( 'block_type_metadata', 'example_disable_heading_background_color_and_gradients' );
```

### `block_type_metadata_settings`

Filters the settings determined from the processed block type metadata. It makes it possible to apply custom modifications using the block metadata that isn’t handled by default.

The callback function for this filter receives two parameters:

- `$settings` (`array`): Array of determined settings for registering a block type.
- `$metadata` (`array`): Metadata loaded from the `block.json` file.

The following example increases the `apiVersion` for all blocks by `1`.

``` php
function example_filter_metadata_registration( $settings, $metadata ) {
$settings['api_version'] = $metadata['apiVersion'] + 1;
return $settings;
};
add_filter( 'block_type_metadata_settings', 'example_filter_metadata_registration', 10, 2 );
```

### `register_block_type_args`

Filters a block’s arguments array (`$args`) right before the block type is officially registered on the server.

The callback function for this filter receives two parameters:

- `$args` (`array`): Array of arguments for registering a block type.
- `$block_type` (`string`): Block type name including namespace.

`register_block_type_args` is the most low-level PHP filter available, and it will work for every block registered on the server. All settings defined on the server are propagated to the client with higher priority than those set in the client.

The following code will disable the color controls for Paragraph, Heading, List, and List Item blocks.

``` php
function example_disable_color_for_specific_blocks( $args, $block_type ) {

// List of block types to modify.
$block_types_to_modify = [
'core/paragraph',
'core/heading',
'core/list',
'core/list-item'
];

// Check if the current block type is in the list.
if ( in_array( $block_type, $block_types_to_modify, true ) ) {
// Disable color controls.
$args['supports']['color'] = array(
'text' => false,
'background' => false,
'link' => false,
);
}

return $args;
}
add_filter( 'register_block_type_args', 'example_disable_color_for_specific_blocks', 10, 2 );
```

### `blocks.registerBlockType`

Used to filter the block settings when registering the block on the client with JavaScript. It receives the block settings, the name of the registered block, and either null or the deprecated block settings (when applied to a registered deprecation) as arguments. This filter is also applied to each of a block’s deprecated settings.

The following example ensures that List blocks are saved with the canonical generated class name (`wp-block-list`):

``` js
function addListBlockClassName( settings, name ) {
if ( name !== 'core/list' ) {
return settings;
}

return {
...settings,
supports: {
...settings.supports,
className: true,
},
};
}

wp.hooks.addFilter(
'blocks.registerBlockType',
'my-plugin/class-names/list-block',
addListBlockClassName
);
```

## Front end

The following PHP filters are available to change the output of a block on the front end.

### `render_block`

Filters the front-end content of any block. This filter has no impact on the behavior of blocks in the Editor.

The callback function for this filter receives three parameters:

- `$block_content` (`string`): The block content.
- `$block` (`array`): The full block, including name and attributes.
- `$instance` (`WP_Block`): The block instance.

In the following example, the class `example-class` is added to all Paragraph blocks on the front end. Here the [HTML API](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/) is used to easily add the class instead of relying on regex.

``` php
function example_add_custom_class_to_paragraph_block( $block_content, $block ) {

// Check if the block is a Paragraph block.
if ( 'core/paragraph' === $block['blockName'] ) {

// Add the custom class to the block content using the HTML API.
$processor = new WP_HTML_Tag_Processor( $block_content );

if ( $processor->next_tag( 'p' ) ) {
$processor->add_class( 'example-class' );
}

return $processor->get_updated_html();
}

return $block_content;
}
add_filter( 'render_block', 'example_add_custom_class_to_paragraph_block', 10, 2 );
```

### `render_block_{namespace/block}`

Filters the front-end content of the defined block. This is just a simpler form of `render_block` when you only need to modify a specific block type.

The callback function for this filter receives three parameters:

- `$block_content` (`string`): The block content.
- `$block` (`array`): The full block, including name and attributes.
- `$instance` (`WP_Block`): The block instance.

In the following example, the class `example-class` is added to all Paragraph blocks on the front end. Notice that compared to the `render_block` example above, you no longer need to check the block type before modifying the content. Again, the [HTML API](https://make.wordpress.org/core/2023/03/07/introducing-the-html-api-in-wordpress-6-2/) is used instead of regex.

``` php
function example_add_custom_class_to_paragraph_block( $block_content, $block ) {

// Add the custom class to the block content using the HTML API.
$processor = new WP_HTML_Tag_Processor( $block_content );

if ( $processor->next_tag( 'p' ) ) {
$processor->add_class( 'example-class' );
}

return $processor->get_updated_html();
}
add_filter( 'render_block_core/paragraph', 'example_add_custom_class_to_paragraph_block', 10, 2 );
```

## Editor

The following JavaScript filters are available to change the behavior of blocks while editing in the Editor.

### `blocks.getSaveElement`

A filter that applies to the result of a block’s `save` function. This filter is used to replace or extend the element, for example using `React.cloneElement` to modify the element’s props, replace its children, or return an entirely new element.

The callback function for this filter receives three parameters:

- `element` (`Object`): The element to be modified and returned.
- `blockType` (`Object`): A block-type definition object.
- `attributes` (`Object`): The block’s attributes.

The following example wraps a Cover block in an outer container `div`.

``` js
function wrapCoverBlockInContainer( element, blockType, attributes ) {

// Skip if element is undefined.
if ( ! element ) {
return;
}

// Only apply to Cover blocks.
if ( blockType.name !== 'core/cover' ) {
return element;
}

// Return the element wrapped in a div.
return { element };
}

wp.hooks.addFilter(
'blocks.getSaveElement',
'my-plugin/wrap-cover-block-in-container',
wrapCoverBlockInContainer
);
```

### `blocks.getSaveContent.extraProps`

A filter that applies to all blocks returning a WP Element in the `save` function. This filter is used to add extra props to the root element of the `save` function. For example, you could add a className, an id, or any valid prop for this element.

The callback function for this filter receives three parameters:

- `props` (`Object`): The current `save` element’s props to be modified and returned.
- `blockType` (`Object`): A block-type definition object.
- `attributes` (`Object`): The block’s attributes.

The following example adds a red background by default to all blocks.

``` js
function addBackgroundColorStyle( props ) {
return {
...props,
style: { backgroundColor: 'red' },
};
}

wp.hooks.addFilter(
'blocks.getSaveContent.extraProps',
'my-plugin/add-background-color-style',
addBackgroundColorStyle
);
```

*Note:* A [block validation](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/#validation) error will occur if this filter modifies existing content the next time the post is edited. The Editor verifies that the content stored in the post matches the content output by the `save()` function.

To avoid this validation error, use `render_block` server-side to modify existing post content instead of this filter. See [render_block documentation](https://developer.wordpress.org/reference/hooks/render_block/).

### `blocks.getBlockDefaultClassName`

Generated HTML classes for blocks follow the `wp-block-{name}` nomenclature. This filter allows to provide an alternative class name.

``` js
// Our filter function.
function setBlockCustomClassName( className, blockName ) {
return blockName === 'core/code' ? 'my-plugin-code' : className;
}

// Adding the filter.
wp.hooks.addFilter(
'blocks.getBlockDefaultClassName',
'my-plugin/set-block-custom-class-name',
setBlockCustomClassName
);
```

### `blocks.switchToBlockType.transformedBlock`

Used to filter an individual transform result from block transformation. All of the original blocks are passed since transformations are many-to-many, not one-to-one.

### `blocks.getBlockAttributes`

Called immediately after the default parsing of a block’s attributes and before validation to allow a plugin to manipulate attribute values in time for validation and/or the initial values rendering of the block in the editor.

The callback function for this filter accepts 4 parameters:\
– `blockAttributes` (`Object`): All block attributes.\
– `blockType` (`Object`): The block type.\
– `innerHTML` (`string`): Raw block content.\
– `attributes` (`object`): Known block attributes (from delimiters).

In the example below, we use the `blocks.getBlockAttributes` filter to lock the position of all paragraph blocks on a page.

``` js
// Our filter function
function lockParagraphs( blockAttributes, blockType, innerHTML, attributes ) {
if('core/paragraph' === blockType.name) {
blockAttributes['lock'] = {move: true}
}
return blockAttributes;
}

// Add the filter
wp.hooks.addFilter(
'blocks.getBlockAttributes',
'my-plugin/lock-paragraphs',
lockParagraphs
);
```

### `editor.BlockEdit`

Used to modify the block’s `edit` component. It receives the original block `BlockEdit` component and returns a new wrapped component.

The following example adds a new Inspector panel for all blocks.

``` js
const { createHigherOrderComponent } = wp.compose;
const { InspectorControls } = wp.blockEditor;
const { PanelBody } = wp.components;

const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
return ( props ) => {
return (
<>

My custom control

);
};
}, 'withMyPluginControls' );

wp.hooks.addFilter(
'editor.BlockEdit',
'my-plugin/with-inspector-controls',
withMyPluginControls
);
```

Note that as this hook is run for *all blocks*, consuming it has the potential for performance regressions, particularly around block selection metrics.

To mitigate this, consider whether any work you perform can be altered to run only under certain conditions.

For example, suppose you are adding components that only need to render when the block is *selected*. In that case, you can use the block’s “selected” state (`props.isSelected`) to conditionalize your rendering.

The following example adds a new Inspector panel for all blocks, but only when a block is selected.

``` js
const withMyPluginControls = createHigherOrderComponent( ( BlockEdit ) => {
return ( props ) => {
return (
<>

{ props.isSelected && (

My custom control

) }

);
};
}, 'withMyPluginControls' );
```

### `editor.BlockListBlock`

Used to modify the block’s wrapper component containing the block’s `edit` component and all toolbars. It receives the original `BlockListBlock` component and returns a new wrapped component.

The following example adds a unique class name to all blocks.

``` js
const { createHigherOrderComponent } = wp.compose;

const withClientIdClassName = createHigherOrderComponent(
( BlockListBlock ) => {
return ( props ) => {
return (

);
};
},
'withClientIdClassName'
);

wp.hooks.addFilter(
'editor.BlockListBlock',
'my-plugin/with-client-id-class-name',
withClientIdClassName
);
```

You can add new properties to the block’s wrapper component using the `wrapperProps` property of the returned component as shown in the following example.

``` js
const { createHigherOrderComponent } = wp.compose;
const withMyWrapperProp = createHigherOrderComponent( ( BlockListBlock ) => {
return ( props ) => {
const wrapperProps = {
...props.wrapperProps,
'data-my-property': 'the-value',
};
return ;
};
}, 'withMyWrapperProp' );

wp.hooks.addFilter(
'editor.BlockListBlock',
'my-plugin/with-my-wrapper-prop',
withMyWrapperProp
);
```

### `editor.postContentBlockTypes`

Used to modify the list of blocks that should be enabled even when used inside a locked template. Any block that saves data to a post should be added here. An example of this is the Post Featured Image block. Often used in templates, this block should still allow selecting the image even when the template is locked.

The following example enables the fictitious block `namespace/example`.

``` js
const addExampleBlockToPostContentBlockTypes = ( blockTypes ) => {
return [ ...blockTypes, 'namespace/example' ];
};

wp.hooks.addFilter(
'editor.postContentBlockTypes',
'my-plugin/post-content-block-types',
addExampleBlockToPostContentBlockTypes
);
```

## Removing Blocks

### Using a deny list

Adding blocks is easy enough, and removing them is as easy. Plugin or theme authors can “unregister” blocks using a deny list in JavaScript.

Place the following code in a `my-plugin.js` file.

``` js
// my-plugin.js
import { unregisterBlockType } from '@wordpress/blocks';
import domReady from '@wordpress/dom-ready';

domReady( function () {
unregisterBlockType( 'core/verse' );
} );
```

Then, load this script in the Editor using the following function.

``` php

When unregistering a block, there can be a [race condition](https://en.wikipedia.org/wiki/Race_condition) on which code runs first: registering the block or unregistering the block. You want your unregister code to run last. To do this, you must specify the component that is registering the block as a dependency, in this case, `wp-edit-post`. Additionally, using `wp.domReady()` ensures the unregister code runs once the dom is loaded.}
### Using an allow list If you want to disable all blocks except an allow list, you can adapt the script above like so: ``` js // my-plugin.js var allowedBlocks = [ 'core/paragraph', 'core/image', 'core/html', 'core/freeform', ]; wp.blocks.getBlockTypes().forEach( function ( blockType ) { if ( allowedBlocks.indexOf( blockType.name ) === -1 ) { wp.blocks.unregisterBlockType( blockType.name ); } } ); ``` ## Hiding blocks from the inserter ### `allowed_block_types_all`
Before WordPress 5.8, this hook was known as `allowed_block_types`, which is now deprecated. If you need to support older versions of WordPress, you might need a way to detect which filter should be used. You can check if `allowed_block_types` is safe to use by seeing if the `WP_Block_Editor_Context` class exists, which was introduced in 5.8.
On the server, you can filter the list of blocks shown in the inserter using the `allowed_block_types_all` filter. You can return either true (all block types supported), false (no block types supported), or an array of block type names to allow. You can also use the second provided parameter `$editor_context` to filter block types based on their content. ``` php post ) ) { return array( 'core/paragraph', 'core/heading' ); } return $allowed_block_types; } add_filter( 'allowed_block_types_all', 'example_filter_allowed_block_types_when_post_provided', 10, 2 ); ``` ## Managing block categories ### `block_categories_all`
Before WordPress 5.8, this hook was known as `block_categories`, which is now deprecated. If you need to support older versions of WordPress, you might need a way to detect which filter should be used. You can check if `block_categories` is safe to use by seeing if the `WP_Block_Editor_Context` class exists, which was introduced in 5.8.
It is possible to filter the list of default block categories using the `block_categories_all` filter. You can do it on the server by implementing a function which returns a list of categories. It is going to be used during block registration and to group blocks in the inserter. You can also use the second provided parameter `$editor_context` to filter the based on its content. ``` php // my-plugin.php function example_filter_block_categories_when_post_provided( $block_categories, $editor_context ) { if ( ! empty( $editor_context->post ) ) { array_push( $block_categories, array( 'slug' => 'custom-category', 'title' => __( 'Custom Category', 'custom-plugin' ), 'icon' => null, ) ); } return $block_categories; } add_filter( 'block_categories_all', 'example_filter_block_categories_when_post_provided', 10, 2 ); ``` ### `wp.blocks.updateCategory` You can also display an icon with your block category by setting an `icon` attribute. The value can be the slug of a [WordPress Dashicon](https://developer.wordpress.org/resource/dashicons/). You can also set a custom icon in SVG format. To do so, the icon should be rendered and set on the frontend, so it can make use of WordPress SVG, allowing mobile compatibility and making the icon more accessible. To set an SVG icon for the category shown in the previous example, add the following example JavaScript code to the Editor calling `wp.blocks.updateCategory` e.g: ``` js ( function () { var el = React.createElement; var SVG = wp.primitives.SVG; var circle = el( 'circle', { cx: 10, cy: 10, r: 10, fill: 'red', stroke: 'blue', strokeWidth: '10', } ); var svgIcon = el( SVG, { width: 20, height: 20, viewBox: '0 0 20 20' }, circle ); wp.blocks.updateCategory( 'my-category', { icon: svgIcon } ); } )(); ``` # Editor Hooks WordPress exposes several APIs that allow you to modify the editor experience. ## Editor settings One of the most common ways to modify the Editor is through the [`block_editor_settings_all`](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/) PHP filter, which is applied before settings are sent to the initialized Editor. This filter allows plugin and theme authors extensive control over how the Editor behaves.
Before WordPress 5.8, this hook was known as `block_editor_settings`, which is now deprecated. If you need to support older versions of WordPress, you might need a way to detect which filter should be used. You can check if `block_editor_settings` is safe to use by seeing if the `WP_Block_Editor_Context` class exists, which was introduced in 5.8.
The `block_editor_settings_all` hook passes two parameters to the callback function: - `$settings` – An array of configurable settings for the Editor. - `$context` – An instance of [`WP_Block_Editor_Context`](https://developer.wordpress.org/reference/classes/wp_block_editor_context/), an object that contains information about the current Editor. The following example modifies the maximum upload file size. Add this to a plugin or your theme’s `functions.php` file to test it. ``` php add_filter( 'block_editor_settings_all', 'example_filter_block_editor_settings_when_post_provided', 10, 2 ); function example_filter_block_editor_settings_when_post_provided( $editor_settings, $editor_context ) { if ( ! empty( $editor_context->post ) ) { $editor_settings['maxUploadFileSize'] = 12345; } return $editor_settings; } ``` There are dozens of editor settings, too many to list in this documentation article, but here are a few examples of what you can do with the `block_editor_settings_all` filter.
To view all available settings, open the Editor and then open the console in your browser’s [Developer Tools](https://developer.wordpress.org/advanced-administration/debug/debug-javascript/#open-the-developer-tools). Enter the command `wp.data.select( 'core/block-editor' ).getSettings()` to display the current values for all Editor settings.
### Restrict code editor access The `codeEditingEnabled`, which defaults to `true`, controls whether the user can access the code editor **in addition** to the visual editor. There may be instances where you don’t want certain users to be able to access this view. If this setting is set to `false`, the user will not be able to switch between visual and code editor. The option in the settings menu will not be available, and the keyboard shortcut for switching editor types will not fire. Here’s an example: ``` php add_filter( 'block_editor_settings_all', 'example_restrict_code_editor' ); function example_restrict_code_editor( $settings ) { $can_active_plugins = current_user_can( 'activate_plugins' ); // Disable the Code Editor for users that cannot activate plugins (Administrators). if ( ! $can_active_plugins ) { $settings[ 'codeEditingEnabled' ] = false; } return $settings; } ``` ### Restrict visual editor access Similar to the `codeEditingEnabled` setting, `richEditingEnabled` allows you to control who can access the visual editor. If `true`, the user can edit the content using the visual editor. The setting defaults to the returned value of the [`user_can_richedit`](https://developer.wordpress.org/reference/functions/user_can_richedit/) function. It checks whether the user can access the visual editor and whether the user’s browser supports it. ### Restrict responsive editing The `responsiveEditingEnabled` setting, which defaults to `true`, controls whether the “Responsive styles” option is available in the Editor’s View menu. When it is `false`, the option is not rendered, and the viewport state control in Global Styles is hidden as well, so users cannot target style changes at a single viewport. Pseudo states such as hover remain available. Responsive styles already defined in the theme or in Global Styles are unaffected. ``` php add_filter( 'block_editor_settings_all', 'example_disable_responsive_editing' ); function example_disable_responsive_editing( $settings ) { $settings['responsiveEditingEnabled'] = false; return $settings; } ``` ### Restrict block states editing The `blockStatesEditingEnabled` setting, which defaults to `true`, controls whether state controls for blocks are available in the block inspector and Global Styles. When it is `false`, those controls are not rendered, so users cannot apply block styles to states from those UIs. Viewport state controls are unaffected and remain controlled by `responsiveEditingEnabled`. State styles already saved in `theme.json`, in Global Styles, or in a block’s `style` attribute are unaffected. ``` php add_filter( 'block_editor_settings_all', 'example_disable_block_states_editing' ); function example_disable_block_states_editing( $settings ) { $settings['blockStatesEditingEnabled'] = false; return $settings; } ``` ### Set a default image size Images are set to the `large` image size by default in the Editor. You can modify this using the `imageDefaultSize` setting, which is especially useful if you have configured your own custom image sizes. The following example changes the default image size to `medium`. ``` php add_filter( 'block_editor_settings_all', 'example_set_default_image_size' ); function example_set_default_image_size( $settings ) { $settings['imageDefaultSize'] = 'medium'; return $settings; } ``` ### Disable Openverse The [Openverse](https://openverse.org/) integration is enabled for all WordPress sites by default and is controlled by the `enableOpenverseMediaCategory` setting. To disable Openverse, apply the following filter: ``` php add_filter( 'block_editor_settings_all', 'example_disable_openverse' ); function example_disable_openverse( $settings ) { $settings['enableOpenverseMediaCategory'] = false; return $settings; } ``` ### Disable the Font Library The Font Library allows users to install new fonts on their site, which is enabled by default and is controlled by the `fontLibraryEnabled` setting. To disable the Font Library, apply the following filter: ``` php add_filter( 'block_editor_settings_all', 'example_disable_font_library' ); function example_disable_font_library( $settings ) { $settings['fontLibraryEnabled'] = false; return $settings; } ``` ### Disable block inspector tabs Most blocks display [two tabs](https://make.wordpress.org/core/2023/03/07/introduction-of-block-inspector-tabs/) in the Inspector, one for Settings and another for Styles. You can disable these tabs using the `blockInspectorTabs` setting. ``` php add_filter( 'block_editor_settings_all', 'example_disable_inspector_tabs_by_default' ); function example_disable_inspector_tabs_by_default( $settings ) { $settings['blockInspectorTabs'] = array( 'default' => false ); return $settings; } ``` You can also modify which blocks have inspector tabs. Here’s an example that disables tabs for a specific block. ``` php add_filter( 'block_editor_settings_all', 'example_disable_tabs_for_my_custom_block' ); function example_disable_tabs_for_my_custom_block( $settings ) { $current_tab_settings = _wp_array_get( $settings, array( 'blockInspectorTabs' ), array() ); $settings['blockInspectorTabs'] = array_merge( $current_tab_settings, array( 'my-plugin/my-custom-block' => false ) ); return $settings; } ``` ## Block Directory The Block Directory allows users to install new block plugins directly in the Editor from the WordPress.org [Plugin Directory](https://wordpress.org/plugins/browse/block/). You can disable this functionality by removing the action that enqueues it, which is `wp_enqueue_editor_block_directory_assets`. To do so, use [`remove_action`](https://developer.wordpress.org/reference/functions/remove_action/) like this: ``` php remove_action( 'enqueue_block_editor_assets', 'wp_enqueue_editor_block_directory_assets' ); ``` ## Block patterns Remote patterns, such as those from the WordPress.org [Pattern Directory](https://wordpress.org/patterns/), are available to users by default in the Editor. This functionality is controlled by `should_load_remote_block_patterns`, which defaults to `true`. You can disable remote patterns by setting the filter to false (`__return_false`). ``` php add_filter( 'should_load_remote_block_patterns', '__return_false' ); ``` ## Editor features The following filters are available to extend features in the Editor. ### `editor.PostFeaturedImage.imageSize` You can use this filter to modify the image size displayed in the Post Featured Image component. It defaults to `'post-thumbnail'` and will fail back to the `full` image size when the specified image size doesn’t exist in the media object. It’s modeled after the `admin_post_thumbnail_size` filter in the Classic Editor. ``` js import { addFilter } from '@wordpress/hooks'; const withImageSize = function ( size, mediaId, postId ) { return 'large'; }; addFilter( 'editor.PostFeaturedImage.imageSize', 'my-plugin/with-image-size', withImageSize ); ``` ### `editor.PostPreview.interstitialMarkup` You can also filter the interstitial message shown when generating previews. Here’s an example: ``` js import { addFilter } from '@wordpress/hooks'; const customPreviewMessage = function () { return 'Post preview is being generated!'; }; addFilter( 'editor.PostPreview.interstitialMarkup', 'my-plugin/custom-preview-message', customPreviewMessage ); ``` ### `media.crossOrigin` This filter is used to set or modify the `crossOrigin` attribute for foreign-origin media elements (i.e., `