Unregistering style variations in a WordPress block theme

When building a custom theme or working with a child theme, you might need to remove or hide certain styling features, whether it’s for a single core block or a full theme style variation.

Doing so isn’t just about preference. It often brings practical advantages, such as improved performance, more consistent design, and a simpler user interface.

The approaches taken to accomplish these goals vary and are likely to depend on your needs and your skills. For the examples in this article, we work with a child theme of Twenty Twenty-Five (TT5), a modern WordPress block theme.

Unregistering depends on how it was registered

For our purposes, when we refer to unregistering a block or theme style variation, we distinguish between complete and partial removal, and whether the variation is fully removed or merely hidden from the interface. The distinctions are important.

Understanding how to unregister a block starts with knowing how it was registered. For example, core blocks registered with JavaScript are best unregistered in that language. By contrast, theme style variations are registered with PHP, and thus, a different approach may be in order.

Unregistering custom blocks is outside the scope of this article, and your approach depends on how those blocks were originally registered.

What is a style variation?

WordPress distinguishes between block styles and theme style variations. Block styles are visual alternatives for a specific block, such as a button block’s “fill” or “outline” styles. Block style variations are registered in core, theme.json, block.json (or in a plugin).

Theme style variations, on the other hand, are entire visual alternatives that include colors, typography, and layouts defined in a unique theme.json file. They allow users to switch between different looks (skins) for a site without changing the theme. TT5 comes with eight style variations in addition to the default style.

Take your first step: enqueue your scripts

Because we are working with a child theme, you must take care to enqueue your scripts properly.

This setup gets you started, including enqueuing our custom unregister-blocks.js file.

// Enqueue Parent and Child Styles
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );

    wp_enqueue_style(
        'child-style',
        get_stylesheet_uri(),
        ['parent-style'],
        wp_get_theme()->get('Version')
    );
});

// Enqueue styles in the WordPress admin
add_action('admin_enqueue_scripts', function () {
    wp_enqueue_style(
        'child-admin-style',
        get_stylesheet_uri(),
        [],
        wp_get_theme()->get('Version')
    );
});

// Enqueue JavaScript for block editor
add_action('enqueue_block_editor_assets', function () {
    wp_enqueue_script(
        'unregister-core-blocks',
        get_stylesheet_directory_uri() . '/js/unregister-blocks.js',
        ['wp-blocks', 'wp-dom-ready', 'wp-edit-post'],
        null,
        true
    );
});

As you can see, we have a JavaScript file at js/unregister-blocks.js, which includes all of our scripts for this article.

Do not use get_template_directory_uri() for the JavaScript file, as this points to the parent theme.

Timing is everything

Knowing when a hook fires is critical when working with PHP in WordPress. You should be familiar with the basic loading sequence, which begins in wp-settings.php:

• Constants
• Globals
• Core components
• Load plugins
• Load the theme

Figuring out the right point at which a custom function should run is one of the trickiest and most frustrating parts of WordPress development.

Unregistering a core block style

Let’s consider a situation in which you wish to remove the style of a core block. In this case, we want to remove the outline style for the button block.

As the fill and outline button styles are registered in TT5’s theme.json file, we use JavaScript to handle the process.

wp.domReady(() => {
    if (wp.blocks && wp.blocks.unregisterBlockStyle) {
        wp.blocks.unregisterBlockStyle('core/button', 'outline');
    }
});

The result is the removal of the outline style in the toolbar and sidebar.