Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Register Block Styles and Variations

How to Register Block Styles and Variations

Short answer

Register a block style with register_block_style in PHP or wp.blocks.registerBlockStyle in JavaScript, giving it a name, a label, and CSS through inline_style, style_handle, or style_data. A block variation is a preset version of a block with fixed starting attributes, registered with registerBlockVariation. Pick the style in the editor styles selector to add its is-style class to the block.

Key takeaways

  • Block styles add a class such as is-style-fancy-quote to the block wrapper.
  • register_block_style needs a name, a label, and inline_style, style_handle, or style_data.
  • Server-side block style registration arrived in WordPress 5.3.
  • style_data, added in WordPress 6.6, lets users edit the style in Global Styles.
  • A block variation presets starting attributes, such as the provider of an Embed block.

What is a block style in WordPress?

A block style is a named alternate look for a block that a reader picks from the styles selector in the editor.

The Block Editor Handbook states that block styles work by adding a class name to the block wrapper, and that class name provides the alternate styling when the style is picked (checked November 2026).

A style never changes the block itself. It only adds a class such as is-style-fancy-quote to the wrapper, and your CSS decides what that class looks like on the page.

Core blocks ship with their own styles already. The Quote block has a Default style and a Large style, and your theme or plugin can add more.

What is a block variation, and how is it different?

A block variation is a preset version of a block with fixed starting settings, while a block style is only a different look for the same block.

The Block Editor Handbook states that a variation differs from the original block by a set of initial attributes or inner blocks (checked November 2026).

The Embed block shows the idea in action. It ships with one variation per provider, such as WordPress and YouTube, so each choice starts with the right provider already set.

Use a style when the block settings stay the same and only the look changes. Use a variation when the starting settings, content, or inner blocks need to differ.

FeatureBlock styleBlock variation
What it changesCSS class on the wrapperStarting attributes or inner blocks
Picked fromStyles selectorInserter or block transforms
Registered withregister_block_style or registerBlockStyleregisterBlockVariation or the variations key
ExampleA blue Quote styleA YouTube Embed preset

What do you need before you register a block style?

You need a theme or plugin file for the PHP code, or a JavaScript file loaded in the editor for the JavaScript route.

For the PHP route, add your code to the theme functions.php file or a plugin file. A child theme is the safer place in a theme, so an update to the parent theme does not wipe your code.

For the JavaScript route, create a script file and load it only in the editor. The Block Editor Handbook shows the script loaded through the enqueue_block_editor_assets hook (checked November 2026).

You also need the block name in namespace form, such as core/quote or core/image. Core block names all start with core/, and the handbook examples use core/quote throughout.

Pick the CSS first. Decide the class name, the label readers will see, and the CSS rules before you write any registration code.

If you want preset groups of blocks instead of a new look, a guide on how to use block patterns covers that option.

How do you register a block style with PHP?

Register a block style in PHP with register_block_style, passing the block name and an array with a name, a label, and your CSS.

The Block Editor Handbook states that the properties array must include name and label, plus one of inline_style, style_handle, or style_data (checked November 2026).

Server-side registration arrived in WordPress 5.3. Make WordPress Core states that WordPress 5.3 added the register_block_style and unregister_block_style PHP helpers for the whole process (checked November 2026).

register_block_style(
    'core/quote',
    array(
        'name'         => 'blue-quote',
        'label'        => __( 'Blue Quote', 'textdomain' ),
        'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
    )
);

The name value becomes part of the CSS class. A style named blue-quote on the Quote block adds the class is-style-blue-quote to the block wrapper.

The three ways to supply the CSS cover three different setups, as the table below shows.

MethodHow the CSS is suppliedBest for
inline_styleCSS written in the registration arrayOne small rule
style_handleHandle of a stylesheet already registered with wp_register_styleCSS shared with other blocks
style_dataTheme.json shaped array of style valuesStyles users can change in Global Styles

The style_data option is the newest of the three. The Block Editor Handbook states that style_data was added in WordPress 6.6 and lets the user change the style through the Global Styles UI under Editor and Styles (checked November 2026).

WordPress 6.6 shipped on July 16, 2024. WordPress.org states that the release, named Dorsey, brought more design options to block themes (checked November 2026).

If your CSS already lives in a stylesheet, register that file first and pass its handle. The handbook example registers myguten-style with wp_register_style and then passes style_handle set to myguten-style.

How do you register a block style with JavaScript?

Register a block style in JavaScript with wp.blocks.registerBlockStyle, passing the block name and an object with a name and a label.

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

The Block Editor Handbook states that picking this style adds the is-style-fancy-quote class name to the block wrapper (checked November 2026).

Load the script only in the editor. Hook a function to enqueue_block_editor_assets and call wp_enqueue_script with the wp-blocks, wp-dom-ready, and wp-edit-post dependencies, as the handbook example shows.

The JavaScript route suits block plugins that already ship editor scripts. The PHP route suits themes and plugins that want the style registered on the server with no extra script file.

Both routes register the same kind of style. A style added in JavaScript shows in the same styles selector as one added in PHP.

The header of a block theme is built from blocks too, so a guide on how to edit the header in a block theme shows where styles apply there.

How do you register a block variation?

Register a block variation with wp.blocks.registerBlockVariation, passing the block name and an object with at least a name and the starting attributes.

wp.blocks.registerBlockVariation( 'core/embed', {
    name: 'custom-embed',
    attributes: { providerNameSlug: 'custom' },
} );

The Block Editor Handbook states that a variation object can hold a name, title, description, category, scope, and an isActive check (checked November 2026).

The name must be unique and machine readable. The title is the human readable name shown in the inserter, and the description explains what the variation is for.

The scope field controls where the variation appears. It defaults to block and inserter, so the variation shows both as a block choice and in the inserter unless you narrow it.

Variations can also be declared when a block is registered, by passing a variations key with an array of variation objects. The handbook states that PHP can add variations too, through the get_block_type_variations filter, and that PHP variations merge with the JavaScript ones (checked November 2026).

Learn WordPress states that the enqueue_block_editor_assets hook loads the JavaScript file, and that the script needs the wp-blocks dependency so it runs only after the blocks package is ready (checked November 2026).

A good variation to build first is a preset for a block you use often. A Heading variation with fixed text, or a Query Loop variation with a set post type, saves your editors from setting the same options every time.

Synced patterns cover a related need, and a guide on how to create reusable blocks walks through them.

How do you make a block style the default?

Add isDefault: true in JavaScript or is_default set to true in PHP to mark a style as the default for its block.

In JavaScript, the Block Editor Handbook states that adding isDefault: true marks the style as active when no custom class name is given, and no custom class is added to the HTML output for that style (checked November 2026).

In PHP, the same handbook states that the is_default property can be set to true to mark one of the block styles as the default when one is missing (checked November 2026).

Only one style per block should be the default. If two styles claim the default, the editor has to pick one, and the result may not match what you planned.

For variations, the isDefault flag works the same way. The Block Editor Handbook states that the editor respects the first registered variation with isDefault, which may not be yours (checked November 2026).

Check the default on a fresh block after you register it. Insert the block without touching the styles selector and confirm the right look is applied.

How do you remove a block style or variation?

Remove a server registered style with unregister_block_style, and a JavaScript style with wp.blocks.unregisterBlockStyle.

unregister_block_style( 'core/quote', 'fancy-quote' );

The Block Editor Handbook states that unregister_block_style only removes styles registered on the server with register_block_style, and does not remove a style registered with client side code (checked November 2026).

For JavaScript, call wp.blocks.unregisterBlockStyle( 'core/quote', 'large' ) to remove the Large style from the Quote block. The handbook warns of a race: your removal code must run after the code that registers the style.

To win that race, list the registering component as a dependency, such as wp-edit-post, and wrap the call in wp.domReady so it runs once the document is loaded. The handbook gives exactly that pattern for removing a style safely.

Remove a variation with wp.blocks.unregisterBlockVariation, passing the block name and the variation name. The handbook example removes the YouTube variation from the Embed block with wp.blocks.unregisterBlockVariation( 'core/embed', 'youtube' ).

Removing a style does not change blocks that already use it. Old posts keep the class in their saved content until someone edits them and picks another style.

What mistakes should you avoid?

The most common mistake is registering the same style twice, once in PHP and once in JavaScript, and then wondering why it appears twice.

Keep one registration per style in one place. If the theme registers it in PHP, the plugin should not register the same name again in JavaScript.

Another mistake is forgetting the label. The name is for code and the CSS class, while the label is what editors read, so a missing label leaves the styles selector with a poor name.

A third mistake is styling with a class name that another plugin also uses. Prefix your style names, such as mytheme-blue-quote, so a clash does not restyle your blocks by surprise.

WordPress 6.6 also lets one style variation cover a whole section of blocks at once. Make WordPress Core states that section styles can be registered across multiple block types at the same time, and that a variation defined in a theme.json partial under the theme /styles folder registers itself (checked November 2026).

Test on a staging copy before you ship. A guide on how to use theme.json explains the theme file that pairs with style data.

A guide on block themes vs classic themes helps you pick the theme type that fits this work.

Frequently asked questions

Can I register a block style without writing JavaScript?

Yes. Use register_block_style in your theme functions.php file or a plugin file, passing the block name and an array with a name, a label, and your CSS. The server-side helpers arrived in WordPress 5.3, so no editor script is needed. Use JavaScript only when your block plugin already loads editor scripts.

What is the difference between a block style and a block variation?

A block style changes only the look of a block by adding a CSS class to its wrapper. A block variation changes the starting setup of a block, such as its attributes or inner blocks. Use a style for a new color or border, and a variation for a preset such as an Embed block fixed to one provider.

Why is my new block style not showing in the editor?

Check three things. First, confirm the code runs: PHP goes in functions.php or a plugin file, and JavaScript must load through enqueue_block_editor_assets. Second, check the block name uses the right namespace, such as core/quote. Third, clear any cache, since a cached editor page can hide a new style.

Can a block style apply to more than one block?

Yes, in WordPress 6.6 and later. The style_data option accepts an array of block names, so one style can cover several blocks at once. Section styles in 6.6 also let a variation apply to a whole section of blocks. With inline_style or style_handle, register the style once per block instead.

Do block styles work in classic themes?

Yes. Block styles work in any theme that uses the block editor, including classic themes. The registration functions are the same either way. The style_data option and section styles need WordPress 6.6 or later, while the basic PHP and JavaScript registration works from WordPress 5.3 onward.

Sources

  1. Styles – Block Editor Handbook WordPress Developer Resources
  2. Variations – Block Editor Handbook WordPress Developer Resources
  3. New Block APIs in WordPress 5.3 Make WordPress Core
  4. Section Styles Make WordPress Core
  5. WordPress 6.6 “Dorsey” WordPress.org
  6. Block Variations Learn WordPress

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test