Day 12: Creating Custom Block Categories and Collections in Gutenberg

Introduction

Welcome to Day 12 of the Gutenberg series! Today, we’ll dive into creating custom block categories and collections in WordPress. This is especially useful when you have multiple custom blocks and want to provide better organization for users in the Block Editor.

By creating custom categories and grouping blocks into collections, you can make it easier for users to find the blocks they need, ensuring a smoother content creation experience.

In this guide, you’ll learn how to:

• Create a custom block category.
• Assign blocks to specific categories.
• Organize multiple blocks into a cohesive collection.

What are Block Categories and Collections?

In the WordPress Block Editor (Gutenberg), blocks are organized into categories to help users find the right block easily. WordPress provides several default categories like Text, Media, Design, and Widgets, but you can create custom categories to group your custom blocks together.

Block collections, on the other hand, are groups of related blocks that share a common purpose or design. For instance, if you’re building a plugin or a theme that comes with multiple custom blocks (like testimonials, call-to-action buttons, or product listings), you can organize these blocks into a custom collection for better discoverability.

Step 1: Creating a Custom Block Category

To create a custom block category, we need to use the block_categories_all filter to register a new category in the WordPress editor.

1. Add Custom Category in functions.php:

Add the following code to your theme’s functions.php file or your plugin’s main file:

function my_theme_custom_block_category( $categories ) {
    return array_merge(
        array(
            array(
                'slug'  => 'my-custom-category',
                'title' => __( 'My Custom Blocks', 'my-theme' ),
                'icon'  => 'wordpress', // Optional: Add an icon for the category
            ),
        ),
        $categories
    );
}
add_filter( 'block_categories_all', 'my_theme_custom_block_category', 10, 2 );

Explanation:

• block_categories_all: This filter allows you to modify the list of block categories in the editor.
• slug: This is the unique identifier for your custom category.
• title: This is the name of your category as it will appear in the block inserter.
• icon: (Optional) You can add an icon from the WordPress Dashicons library for visual identification.

Once this code is added, the new category “My Custom Blocks” will appear in the block inserter when you open the Block Editor.

Step 2: Assigning Blocks to the Custom Category

Now that we have a custom block category, let’s assign some blocks to it.

1. Assign Blocks to the Category:

If you’ve created custom blocks using registerBlockType, you can add the custom category like this:

// Register a custom block and assign it to the custom category
import { registerBlockType } from '@wordpress/blocks';

registerBlockType('my-theme/custom-block', {
    title: 'Custom Block',
    category: 'my-custom-category', // Assign to custom category
    icon: 'block-default',
    edit: () => <div>Custom Block Content</div>,
    save: () => <div>Custom Block Content</div>,
});

Explanation:

• category: This specifies the block category to which the block belongs. In this case, we’ve assigned it to the custom category “my-custom-category” that we created earlier.

Now, when users search for blocks in the My Custom Blocks category, they’ll see your custom blocks grouped together.

Step 3: Grouping Blocks into a Collection

When creating multiple blocks that serve a similar function (e.g., blocks for testimonials, pricing tables, or call-to-action buttons), grouping them into a block collection helps with organization.

A block collection is essentially a group of related blocks within the same custom category. For example, if you’re developing a suite of blocks for a theme or plugin, you can group them under one category (like My Custom Blocks) to keep them organized.

Example: Grouping Multiple Blocks in a Collection

Let’s say you’ve created three blocks: Testimonial, Pricing Table, and CTA Button. All these blocks belong to the same collection. Here’s how you’d register them under your custom category:

// Register Testimonial Block
registerBlockType('my-theme/testimonial-block', {
    title: 'Testimonial Block',
    category: 'my-custom-category',
    icon: 'format-quote',
    edit: () => <div>Testimonial Content</div>,
    save: () => <div>Testimonial Content</div>,
});

// Register Pricing Table Block
registerBlockType('my-theme/pricing-table-block', {
    title: 'Pricing Table Block',
    category: 'my-custom-category',
    icon: 'table-col-before',
    edit: () => <div>Pricing Table Content</div>,
    save: () => <div>Pricing Table Content</div>,
});

// Register CTA Button Block
registerBlockType('my-theme/cta-button-block', {
    title: 'CTA Button Block',
    category: 'my-custom-category',
    icon: 'button',
    edit: () => <div>Call to Action Button</div>,
    save: () => <div>Call to Action Button</div>,
});

Explanation:

• Each block is assigned to the same category (my-custom-category), grouping them together into a collection.

When users open the block inserter, they’ll see all of these blocks listed under the My Custom Blocks category, making it easier to find and use them as part of a cohesive collection.

Step 4: Testing the Custom Category and Collection

To test the custom block category and the collection:

1. Open the Block Editor:
   • Go to any post or page in WordPress and open the Block Editor.
2. Insert a Block:
   • Click the “+” button to add a block.
   • Scroll down or search for “My Custom Blocks”.
3. Use the Blocks:
   • You should see your custom blocks (Testimonial Block, Pricing Table Block, CTA Button Block) grouped under the custom category.
   • Select any block to use it in the editor.

Best Practices for Organizing Blocks

1. Create Logical Categories: Group related blocks into custom categories that make sense for your theme or plugin. For example, if you’re creating blocks for an eCommerce site, you might group them under categories like “Product Blocks” or “Store Layouts”.
2. Use Clear Names: Make sure that both the category and block names are clear and descriptive. This makes it easier for users to identify and use the blocks they need.
3. Keep Collections Manageable: Don’t overload a category with too many blocks. If you have a large number of blocks, consider creating subcategories or separate collections.

Conclusion: Organizing Your Blocks for Better Usability

Creating custom block categories and collections in Gutenberg not only enhances organization but also improves the user experience by making it easier to find and use blocks. This is especially important when dealing with multiple custom blocks in a theme or plugin.

In this article, you’ve learned how to:

• Create a custom block category in WordPress.
• Assign custom blocks to a category.
• Group blocks into a collection for better organization.

In Day 13, we’ll explore custom block styles, which will allow you to offer different visual options for your blocks without requiring users to switch blocks entirely.