register-block-extension

registerBlockExtension

The registerBlockExtension API is a wrapper to make it easier to add custom settings which produce classnames or inline styles to any blocks. There are a few problems with using block styles for customizations. For one an editor cannot combine block styles. So you very quickly land in a situation where you need to add many block styles just to give an editor the ability to choose exactly the combination of options they want. That leads to a bad user experience though as the previews take up a ton of space and also make the editor slower due to the overhead of the iframes it creates. So in many cases it is nicer to extend a bock with custom settings to achieve the same goal. The process of registering your own attributes, modifying the blocks edit function, adding the new classname/inline styles to the editor listing and also adding it to the frontend is rather cumbersome though. That is where this API comes in. It is a wrapper for the underlying filters that improves the editorial experience and reduces the amount of code that needs to get maintained in order to extend blocks.

Usage

import { registerBlockExtension } from '@10up/block-components';

/**
 * additional block attributes object
 */
const additionalAttributes = {
    hasBackgroundPattern: {
        type: 'boolean',
        default: false,
    },
    backgroundPatternShape: {
        type: 'string',
        default: 'dots',
    },
    backgroundPatternColor: {
        type: 'string',
        default: 'green'
    }
}

/**
 * BlockEdit
 *
 * a react component that will get mounted in the Editor when the block is
 * selected. It is recommended to use Slots like `BlockControls` or `InspectorControls`
 * in here to put settings into the blocks toolbar or sidebar.
 *
 * @param {object} props block props
 * @returns {JSX}
 */
function BlockEdit(props) {...}

/**
 * generateClassNames
 *
 * a function to generate the new className string that should get added to
 * the wrapping element of the block.
 *
 * @param {object} attributes block attributes
 * @returns {string}
 */
function generateClassNames(attributes) {...}

/**
 * generateInlineStyles
 *
 * a function to generate the new inline styles object that should get added to
 * the wrapping element of the block.
 *
 * @param {object} attributes block attributes
 * @returns {string}
 */
function generateInlineStyles(attributes) {...}

registerBlockExtension(
 'core/group', // also supports adding multiple blocks as an array
 {
  extensionName: 'background-patterns',
  attributes: additionalAttributes,
  classNameGenerator: generateClassNames,
  inlineStyleGenerator: generateInlineStyles,
  Edit: BlockEdit,
  order: 'before',
 }
);

Options

Name	Type	Description
blockName	`string	string[]`
options.extensionName	string	Unique Identifier of the option added
options.attributes	object	Block Attributes that should get added to the block
options.classNameGenerator	function	Function that gets passed the attributes of the block to generate a class name string
options.inlineStyleGenerator	function	Function that gets passed the attributes of the block to generate an inline style object
options.Edit	function	BlockEdit component like in registerBlockType only without the actual block. So only using slots like the InspectorControls is advised.
options.order	string	The order in which the extension should be called in relation to the original BlockEdit component. Can be before or after. Defaults to after

---

unregisterBlockExtension

The unregisterBlockExtension API allows you to remove block extensions that were previously registered using registerBlockExtension. This is particularly useful in child themes or plugins where you need to override or remove functionality provided by a parent theme or another plugin.

Usage

import { unregisterBlockExtension } from '@10up/block-components';

// Unregister a previously registered block extension
unregisterBlockExtension('core/group', 'background-patterns');

// Works with multiple blocks too (same as registerBlockExtension)
unregisterBlockExtension(['core/group', 'core/columns'], 'background-patterns');

// Works with the wildcard selector
unregisterBlockExtension('*', 'background-patterns');

Parameters

Name	Type	Description
blockName	`string	string[]`
extensionName	string	Unique identifier of the extension to unregister

Notes

• The function safely handles cases where the extension was never registered or has already been unregistered
• Both parameters are required - the function will return early if either is missing
• The blockName parameter must match exactly what was used when registering the extension
• For multi-block registrations, you must use the same array of block names or unregister each block individually