Mastering WordPress Custom Block Styles: 6 Powerful Methods for Theme and Plugin Developers

With the rise of the WordPress Block Editor (Gutenberg), developers now have greater flexibility to create visually consistent, reusable design patterns. One powerful way to enhance the editing experience is through custom block styles—offering alternate visual options for core and custom blocks without building entirely new ones.

In this guide, we’ll cover six essential methods theme and plugin developers can use to register and manage custom block styles effectively.

What Are Block Styles in WordPress?

Block styles are predefined visual variations for existing blocks. Instead of creating a custom block from scratch, developers can use block styles to offer alternative designs—for example, a bordered version of a quote block or a button with rounded edges.

6 Ways to Register Custom Block Styles

1. Using register_block_style() in PHP

The core method for themes and plugins.

register_block_style(
‘core/paragraph’,
array(
‘name’ => ‘fancy-border’,
‘label’ => ‘Fancy Border’,
‘style_handle’ => ‘my-theme-styles’,
)
);

✔️ Add this in functions.php or a plugin file.
✔️ Enqueue matching CSS for the style.

2. Adding Block Styles via theme.json (Recommended for Themes)

WordPress 5.9+ supports block styles through theme.json.

jsonCopyEdit{
  "styles": {
    "blocks": {
      "core/paragraph": {
        "border": {
          "radius": "10px"
        }
      }
    }
  }
}

✔️ Cleaner, centralized styling.
✔️ Ideal for full site editing (FSE) themes.

3. Using JavaScript with wp.blocks.registerBlockStyle()

Best for plugins or advanced block behaviors.

jsCopyEditwp.domReady(() => {
  wp.blocks.registerBlockStyle('core/image', {
    name: 'rounded',
    label: 'Rounded Corners',
  });
});

✔️ Add in enqueue_block_editor_assets script.
✔️ You can also use this to unregister default styles.

4. Register Styles for Custom Blocks

If you’ve built a custom block, add styles like this:

jsCopyEditwp.blocks.registerBlockStyle('namespace/custom-block', {
  name: 'outline',
  label: 'Outline Style',
});

✔️ Makes your custom blocks more flexible for users.
✔️ Use naming conventions to organize styles.

5. Use CSS for Styling Block Variants

Each block style adds a class like .is-style-[name] to the block. Use that for styling.

cssCopyEdit.wp-block-quote.is-style-fancy-border {
  border: 2px solid #ccc;
  padding: 10px;
}

✔️ Helps you separate base block styles from optional ones.

6. Load Editor Styles for Better Previews

Ensure your custom block styles look the same in the editor and frontend:

phpCopyEditfunction load_block_editor_styles() {
  add_editor_style('editor-style.css');
}
add_action('admin_init', 'load_block_editor_styles');

✔️ Keeps the editor visually consistent.
✔️ Match backend and frontend appearance.

Bonus Tips

• Use descriptive style names: Avoid vague names like “style1”
• Test on different block types and themes
• Unregister unused block styles for performance

Final Thoughts

Mastering custom block styles allows developers to build more flexible, user-friendly WordPress themes and plugins. Whether you’re using theme.json, PHP, or JavaScript, these six methods give you the tools to create visually engaging layouts that your clients or users can easily apply.