One hook to rule them all: The many faces of block categories

You’ve probably noticed that WordPress blocks come organized in categories. But did you know you don’t have to live with those categories? You can change them around, to make them work for you.

You can rename them. Reorder them. Add completely new categories, including new categories for your custom blocks. And probably do things you or I haven’t even thought of yet.

And you can do all of that with one hook: block_categories_all

The hook is a versatile tool that allows developers to customize the way block categories are organized. Throughout this article you will learn how to use this hook and build functions to add, reorder and rename single or multiple block categories.

Before you dive in it’s important to note that each function accepts a single parameter which is expected to be an array of existing block categories. This is defined as $categories throughout this article.

Adding categories

If you build custom blocks, you might want to put them in some custom categories. You could also have other uses for custom categories—maybe you’re building some sections that have custom styling. Whatever your reasons, here are three approaches:

Creating a new category

Here’s how you can use array_merge to add a new category named Custom Blocks to the end of the existing categories array.

add_filter( 'block_categories_all', 'add_block_category', 10, 2 );

function add_block_category( $categories ) {
    $custom_category = array(
        array(
            'slug'  => 'custom-blocks',
            'title' => __( 'Custom Blocks', 'your-text-domain' ),
            'icon'  => null,
        ),
    );

    return array_merge( $categories, $custom_category );
}

Start by creating a function that accepts a single parameter—remember, it’s expecting the list of existing $categories. Inside the function create a variable named $custom_category and assign an array with these key-value pairs:

• slug — a unique identifier for the category
• title — the display name of the category
• icon — a Dashicon or custom SVG

Note: to my knowledge we’re not using or showing the icon anywhere so in this example you can set this as null.

Then you’ll use the array_merge function to combine $custom_category with the existing $category list. You can position your new category before or after $categories based on the order that you pass each variable into the array_merge.