When you’re creating a custom theme or working with a child theme, there are times when you’ll want to remove or hide particular styling features—whether it’s a single core block or an entire theme style variation.
This isn’t always just about personal preference. Removing unused elements can deliver real benefits, including faster performance, more cohesive design, and a cleaner interface for users.
The best method to accomplish this will vary depending on your goals and your technical expertise. For this guide, we’ll use a child theme based on Twenty Twenty-Five (TT5), a modern WordPress block theme, to illustrate the main techniques.
Table of Contents
Unregistering depends on how it was registered
When we talk about unregistering a block or style variation, it’s important to clarify if we mean a complete removal or simply making it invisible in the UI. Whether you want to fully unregister or just hide elements, the difference matters for both the user experience and how you approach the task.
The process for unregistering depends on how the element was added in the first place. For example, core blocks registered via JavaScript are ideally unregistered with JavaScript, while theme style variations—loaded through PHP—require a different method.
Unregistering custom blocks falls beyond this article’s focus, and your approach there will depend on the block’s registration method.
What is a style variation?
WordPress divides block styles and theme style variations into two categories. Block styles offer visual options for individual blocks, like different button styles. These are set up in core files, theme.json, block.json, or via plugins.
Theme style variations, by contrast, serve as comprehensive visual alternatives defined by their own theme.json files, affecting color palettes, typography, and layouts. This allows users to swap between site “skins” without changing the active theme itself. In TT5, for instance, you’ll find eight different style variations beyond the default.
Take your first step: enqueue your scripts
Since we’re working within a child theme, it’s important to load your scripts correctly.
Set things up by enqueueing your custom unregister-blocks.js file as shown below.
// 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
);
});Here, we’re referencing a JavaScript file at js/unregister-blocks.js, which will contain all the scripts used in these examples.
Be sure not to use get_template_directory_uri() for the JavaScript—this points to the parent theme, not your child theme.
Timing is everything
When customizing WordPress with PHP, understanding hook order is crucial. The loading sequence kicks off in wp-settings.php and generally follows this order:
- Constants
- Globals
- Core components
- Load plugins
- Load the theme
Picking the right timing for your custom functions can be one of the more challenging aspects of WordPress development.
Unregistering a core block style
Let’s say you want to remove a specific style from a core block. For example, you might want to eliminate the outline style for buttons.
Because TT5 registers the “fill” and “outline” button styles in its theme.json file, JavaScript is the preferred approach here.
wp.domReady(() => {
if (wp.blocks && wp.blocks.unregisterBlockStyle) {
wp.blocks.unregisterBlockStyle('core/button', 'outline');
}
});This script removes the outline option from both the block toolbar and the editor sidebar.
Unregistering a core block
If your aim is to eliminate all styles for a block, it often makes more sense to unregister that block entirely. Doing so declutters the Inserter, prevents users from adding the unwanted block, and may benefit performance.
Here’s how you would remove the Quote block as an example.
wp.domReady(() => {
wp.blocks.unregisterBlockType('core/quote');
});If this script runs after the Quote block has already been used in your content, WordPress displays a “This block is no longer available” notice in the editor, but the block’s content still appears on the front end. Users can also choose to edit or convert it to raw HTML if needed.
You can leave it as-is or convert the block to HTML in order to keep the formatting and appearance intact.
To remove multiple blocks at once, you can use a loop. For example, unregistering both the Quote and Heading blocks becomes straightforward:
wp.domReady(() => {
const blocksToRemove = [
'core/quote',
'core/heading',
];
blocksToRemove.forEach((blockName) => {
if (wp.blocks.getBlockType(blockName)) {
wp.blocks.unregisterBlockType(blockName);
}
});
});This approach makes it easy and efficient to manage several blocks simultaneously.
Unregistering a theme style variation
One of the great things about style variations in block themes is that they don’t need explicit registration. Instead, WordPress treats any correctly formatted theme.json—placed in your child theme’s root or /styles directory—as a valid style variation, picking them up automatically.
This doesn’t mean you need a function for unregistration—block themes operate differently. As of now, there isn’t a direct interface for removing unwanted style variations.
Let’s explore the primary methods for managing these variations. The ease of “registering” a style variation by simply adding a file is counterbalanced by the lack of a straightforward removal method. Here’s how you can handle this challenge.
Removing a theme style variation
If you want to remove a style variation, like TT5’s Evening variation, there are a couple of options.
The most direct way, if you’re not using a child theme, is to delete the related .json file—say, 01-evening.json—from the parent theme’s /styles directory. However, this approach isn’t safe, as theme updates will likely restore the file.
The recommended (and safest) solution is to use a child theme to override the unwanted variation. Create an empty file in the same child theme path and with the same filename (e.g., 01-evening.json in your child theme’s /styles directory). This won’t truly unregister the variation but will effectively neutralize it: WordPress will see the file, but without settings, the variation disappears from the UI and becomes nonfunctional. This method works because the child theme is loaded after the parent, so ensure your child theme structure is correct.
Hiding a Variation with CSS
Alternatively, you can use CSS to hide a style variation from the Site Editor. While this method doesn’t actually deregister the variation or remove it from API responses or memory, it will prevent users from selecting it in the editor.
To hide the Evening variation, you can use the following CSS:
/* Hide specific global style variations in the Site Editor */
.edit-site-global-styles-variations_item[data-slug="morning"],
.edit-site-global-styles-variations_item[data-name="evening"],
.edit-site-global-styles-variations_item[title="Evening"],
.edit-site-global-styles-variations_item[aria-label*="Evening"] {
display: none !important;
opacity: 0 !important;
pointer-events: none !important;
}This will remove the variation from the Editor > Styles > Browse Styles panel. Keep in mind: if a user previously activated the Evening variation, the style will still be applied, but switching back to it or reselecting it won’t be possible.
Hiding a Variation with JavaScript
Another method is to run JavaScript—using PHP’s wp_add_inline_script—to hide a style variation in the editor. While this is more of a workaround (since style variations are registered in PHP), it can be useful for suppressing certain UI options when filesystem access isn’t an option.
Here’s how you can implement it:
// Inject JS to hide specific style variations in the Site Editor UI
add_action('enqueue_block_editor_assets', function () {
wp_add_inline_script(
'unregister-core-blocks',
<< {
const interval = setInterval(() => {
document.querySelectorAll(
'[aria-label*="Noon"], [title*="Evening"], [data-name="noon"], [data-slug="evening"]'
).forEach(el => {
el.style.display = 'none';
});
}, 500);
// Stop the interval after 5 seconds
setTimeout(() => clearInterval(interval), 5000);
});
JS
);
});This code waits for the DOM to be ready, then repeatedly checks for and hides the specified variation for a short period. Because it relies on interface class names and timing, it’s a bit fragile, but it does the job in edge cases where direct removal isn’t possible.
Use Cases and Best Practices
It’s important to consider why you might want to unregister blocks or style variations. For example, an agency developing a bespoke website for a client might want to limit choices to ensure design consistency and avoid overwhelming users with irrelevant options. For membership-based or multi-author sites, restricting blocks or styles can help prevent accidental formatting issues and reinforce branding.
Scenarios When Removal Is Preferred
- Performance: Removing unused style variations can result in less CSS/JS being loaded, speeding up both backend and frontend load times.
- Usability: Fewer blocks and styles in the editor make the UI more approachable for non-technical site editors.
- Branding: By unregistering unwanted styles, you ensure only approved color palettes, typography, and design choices are available, keeping site visuals on-message.
- Security and Maintenance: Disabling unused or less secure blocks minimizes future maintenance and update challenges.
Troubleshooting and Tips
- Editor Cache: Sometimes, changes may not appear immediately due to browser caching or block editor caches. Clear the browser cache and perform a hard refresh after making changes.
- Version Conflicts: WordPress and block editor UI classes can change over time. Periodically verify that custom JavaScript or CSS selectors still work after updating WordPress or related plugins.
- Debugging: Use the browser’s developer console to inspect block and style elements if hiding/unregistering does not seem to take effect.
- Custom Plugin vs. Child Theme: If you need to manage blocks/styles across multiple sites, consider packaging your unregister logic as a custom plugin instead of using a child theme.
Advanced: Programmatically Hiding for Specific Roles
You can selectively unregister blocks or hide variations only for certain user roles. For instance, you may want administrators to retain full access, while editors and authors see a simplified set of options. With WordPress’ current_user_can() and conditional JavaScript enqueuing, this becomes straightforward:
if ( ! current_user_can( 'administrator' ) ) {
add_action( 'enqueue_block_editor_assets', function() {
wp_enqueue_script(
'my-childtheme-editor-customizations',
get_stylesheet_directory_uri() . '/js/editor-custom.js',
array( 'wp-blocks', 'wp-dom' ),
filemtime( get_stylesheet_directory() . '/js/editor-custom.js' )
);
});
}This targets only non-admin users and keeps the editor uncluttered for content-focused roles.
Keeping Up to Date with WordPress Changes
WordPress is quickly evolving, especially in the area of block and full site editing. Stay tuned to resources like the WordPress Core blog and release notes for changes related to block registration, theme.json handling, or the Site Editor interface. This helps future-proof your methods for unregistering or hiding unwanted elements and ensures compatibility.
Summary
Tidying up your site by removing unused blocks or style variations can lead to a better experience for both users and administrators and, in many instances, a performance boost as well.
The strategies illustrated here provide reliable ways to unregister or hide style variations. They also highlight why the process can sometimes feel less than straightforward.
