If an existing WordPress block doesn’t fully meet your needs, it can be tempting to build a new one from scratch. Doing so gives you complete control over the block and what your users will see.
While this approach is valid, it often leads to more work and ongoing maintenance, especially if you only need minor enhancements. You’ll not only have to replicate much of the existing block’s functionality, but you’ll also miss out on future updates and improvements made to the original block. This is particularly relevant for Core WordPress blocks, which are frequently updated with new features, improved user interfaces, and more.
Custom blocks are always an option, but it’s usually better to try extending existing blocks before building your own.
There are many ways to extend a block, and this article covers most of them as well as their current limitations. To simplify the discussion, I have divided methods into two sections: the first focuses on APIs for modifying block supports, adding block styles, and registering block variations, while the second shows you how to add fully custom functionality.
Table of Contents
Using block APIs
WordPress includes several APIs that allow you to modify blocks. The Developer Blog has a wealth of content covering these methods, so this section will provide a brief overview of each with links for further reading.
Modifying block supports
The Block Supports API allows you to easily add or modify block features, such as alignment options, color settings, or spacing controls. With just a few lines of code, you can opt a block into or out of specific supports, which will then modify the block’s user interface in the Editor accordingly. For example, text and background color pickers would no longer be displayed for the Heading block if you removed color support.
If you are building a custom block, you should always use the available block supports before adding your own functionality. Doing so gives users a consistent editing experience and ensures your blocks integrate with WordPress features, such as Global Styles.
Supports are generally defined in a block’s block.json file. You can modify these values using either PHP or JavaScript, but often, the best method is to use the register_block_type_args filter in PHP. Doing so removes the need to enqueue an additional JavaScript file and ensures your modifications are registered on the server.
The callback function for this filter accepts two parameters:
$args(array): The block arguments for the registered block type.$block_type(string): The block type name, including namespace.
The following code will enable duotone support on Media & Text blocks. You can place it in your theme’s functions.php file or a utility plugin.
/**
* Enable duotone for Media & Text blocks.
*
* @param array $args The block arguments for the registered block type.
* @param string $block_type The block type name, including namespace.
* @return array The modified block arguments.
*/
function example_enable_duotone_to_media_text_blocks( $args, $block_type ) {
// Only add the filter to Media & Text blocks.
if ( 'core/media-text' === $block_type ) {
$args['supports'] ??= [];
$args['supports']['filter'] ??= [];
$args['supports']['filter']['duotone'] = true;
$args['selectors'] ??= [];
$args['selectors']['filter'] ??= [];
$args['selectors']['filter']['duotone'] = '.wp-block-media-text .wp-block-media-text__media';
}
return $args;
}
add_filter( 'register_block_type_args', 'example_enable_duotone_to_media_text_blocks', 10, 2 );Once applied, you will see the Filters panel in the Settings Sidebar and the available duotone options.