How to Register Block Styles in WordPress?

Block styles are one of the easiest ways to add design variations to core and custom blocks without creating a new block. They help you enrich your theme design system, build reusable visual patterns and give your clients flexible styling options right inside the block editor.

Whether you build themes, plugins or full site builds, understanding how to register block styles is an important skill. In this guide, I will walk you through every possible way to register block styles in WordPress, which versions support specific features and how to decide the best approach for your project.

What are Block Styles in WordPress?

A block style is a visual variation of an existing block. You are not creating a new block. You are adding a style/UI choice for that block.

For example:

• A Button block could have styles like Outline, Filled or Rounded
• A Quote block could have Simple or Decorative variations
• A Group block could have Card or Shadow variations

Each style is a combination of a slug and a label. When a user selects a style, WordPress adds a class to the block so you can style it with CSS.

This makes block styles perfect for theme authors and agencies who want consistent styling without building dozens of custom blocks.

Register Block Styles Using JavaScript

Supported since WordPress 5.3

Best for theme and plugin developers who already enqueue editor scripts.

JavaScript is the modern and preferred method because:

• It works instantly in the block editor
• No page reload is required
• Styles appear where users expect them
• You can register styles conditionally

Basic Example

Create or update your editor script (for example editor.js):

wp.blocks.registerBlockStyle( 'core/quote', {
    name: 'clean-quote',
    label: 'Clean Quote'
} );

You must enqueue this script for the editor:

function mytheme_editor_scripts() {
    wp_enqueue_script(
        'mytheme-block-styles',
        get_template_directory_uri() . '/assets/js/editor.js',
        array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
        true
    );
}
add_action( 'enqueue_block_editor_assets', 'mytheme_editor_scripts' );

Styling the Variation

Add CSS:

.is-style-clean-quote {
    border-left: 4px solid #0057ff;
    padding-left: 1rem;
    font-style: normal;
}

Why use JavaScript to register block styles?

• Cleanest method for editor integration
• Users see styles immediately
• Best for plugins or dynamic conditions
• Works across all block types

Register Block Styles Using PHP

Supported since WordPress 5.3

PHP is great when you want server level registration or do not need editor JS.

Basic Example

register_block_style(
    'core/paragraph',
    array(
        'name'  => 'highlight',
        'label' => 'Highlight'
    )
);

Add this inside a function hooked to init:

function mytheme_register_block_styles() {
    register_block_style(
        'core/paragraph',
        array(
            'name'  => 'highlight',
            'label' => 'Highlight'
        )
    );
}
add_action( 'init', 'mytheme_register_block_styles' );

Styling with Variation

Add CSS:

.is-style-highlight {
    background: #fff3a3;
    padding: 0.2rem 0.4rem;
}

When to use PHP?

• When you want block styles available even if editor JS fails
• When building small themes
• When providing styles that rarely need editor side logic

Register Block Styles in theme.json

Supported since WordPress 6.1

You can define block styles directly in theme.json for core blocks. This method is clean, structured and perfect for block themes.

Basic Example

{
  "version": 2,
  "styles": {
    "blocks": {
      "core/button": {
        "variations": [
          {
            "name": "outline",
            "label": "Outline"
          },
          {
            "name": "dark",
            "label": "Dark Button"
          }
        ]
      }
    }
  }
}

However, styling still requires CSS. theme.json only defines the options.

.is-style-outline {
    border: 2px solid #000;
    background: transparent;
    color: #000;
}

.is-style-dark {
    background: #111;
    color: #fff;
}

When to use theme.json?

• When you build block themes
• When you want a structured design system
• When you want everything centralized
• When you avoid JS

Limitations

• You cannot unregister block styles in declared in theme.json
• Custom blocks must be handled differently depending on how they are built

Register Block Styles using block.json

Supported since WordPress 5.8

You can register block styles using block.json which is only applicable to custom blocks.

Inside your block’s block.json, you can define styles like this:

{
  "name": "myplugin/card",
  "title": "Card",
  "category": "design",
  "style": "file:./style.css",
  "variations": [
    {
      "name": "soft",
      "label": "Soft Card"
    },
    {
      "name": "shadow",
      "label": "Shadow Card"
    }
  ]
}

Then create CSS for these variations:

.is-style-soft {
    background: #f7f7f7;
    padding: 20px;
}

.is-style-shadow {
    box-shadow: 0 8px 24px rgba(0,0,0,0.12);
}

When to use block.json

• When you build plugins
• When creating reusable custom blocks
• When you want variations tied tightly to the block

Unregister Existing Block Styles

Sometimes you want to remove default styles, such as the “Default” and “Rounded” styles on the Image block.

Using JavaScript

wp.blocks.unregisterBlockStyle( 'core/image', 'rounded' );

Using PHP

unregister_block_style( 'core/image', 'rounded' );

Un-registering is helpful when you want strict design control.

Best Practices for Registering Block Styles

I have curated a list of some common best practices that will be helpful in registering block styles:

1. Keep the style slug short and meaningful

Examples:

• soft
• outline
• shadow
• clean
• hero

Note: Avoid long or camel case names.

2. Always add CSS for your block styles

Registering a style without styling it leads to confusing UI.

3. Use theme.json to maintain a clean design system

Keep it simple. Use theme.json to maintain clean design system and use PHP or JS for more advanced logic.

4. Unregister unwanted default block styles

This keeps the editor clean and reduces confusion for clients.

5. Provide consistent naming across your theme

This will help your users and fellow developers understand your design system better this way.

Wrapping Up

Registering block styles is one of the simplest ways to extend the WordPress editor without creating new blocks. Whether you use JavaScript, PHP, theme.json or block.json, each method gives you different levels of control.

If you build modern block themes or custom plugins, knowing all these methods helps you deliver cleaner, more flexible and more scalable WordPress solutions.

If you want help building custom blocks, block themes or advanced WordPress functionality, feel free to explore my WordPress development services or reach out for a custom quote.