When a client asks for “a special kind of button” or “a testimonial box”, the instinct for many developers is to build a custom block. Sometimes that’s right. But often, the block editor already has a block that does ninety percent of the job, and what’s really needed is a predefined look or a preconfigured starting point. WordPress block styles and block variations are built for exactly this situation.
That’s exactly what block styles and block variations are for. They let you extend existing core blocks with new options, without writing a new block from scratch. The result is lighter code, better compatibility with future WordPress versions and a simpler experience for editors, who see familiar blocks with a few extra choices.
The difference in one sentence
A block style changes how a block looks by adding a CSS class. A block variation changes how a block starts, with preset attributes and inner blocks, and can appear as its own item in the inserter.
Both reuse an existing block. Neither changes what the block fundamentally is.
Block styles
When you select a core Button block, the sidebar shows “Fill” and “Outline” under Styles. Those are block styles. Selecting one adds a class like is-style-outline to the block’s wrapper, and CSS does the rest.
You can register your own. For example, a “Pill” button style with fully rounded corners and a “Ghost” style with a transparent background and subtle border.
Registering a style in PHP
The simplest way is in your theme’s functions.php or a plugin:
The name becomes the class suffix, so this adds is-style-pill. The inline_style is output only when the block appears on a page, which keeps CSS lean.
For larger styles, you can reference a registered stylesheet with style_handle instead of inline CSS.
Registering styles in theme.json
Since WordPress 6.6, block themes can define block style variations as JSON files in a styles/blocks folder, or in theme.json, with full design token support. This lets you set colours, typography and spacing using the same presets as the rest of the theme, so styles stay consistent if the palette changes.
| "background": "var:preset | color | accent-soft" |
|---|---|---|
| "padding": "var:preset | spacing | 40" |
| "left": { "width": "4px", "color": "var:preset | color | accent" } |
Saved as styles/blocks/callout.json in a block theme, this adds a “Callout” style to Group blocks. Editors pick it from the Styles panel, and the design follows the theme’s presets.
Removing core styles you don’t want
Sometimes the problem isn’t missing options but too many. If your design system has no place for outline buttons or rounded images, remove them so editors can’t use them:
Enqueue this script for the editor with enqueue_block_editor_assets and declare wp-blocks and wp-dom-ready as dependencies.
Removing options is underrated. Every unnecessary choice is an opportunity for inconsistency.
Limitations of block styles
A block can only have one style active at a time. If you need combinations, such as pill-shaped and large and ghost, styles become unwieldy. In that case, consider whether core design tools like border radius and size controls already cover it, or whether a custom block is justified.
Styles also only add a class. They can’t change the block’s markup or add new settings.
Block variations
Variations are presets for a block. When you insert a Group block, you’re offered Group, Row, Stack and Grid. Those are variations of the same core/group block with different layout attributes. Similarly, the Embed block has variations for YouTube, Vimeo, Spotify and others.
You can register variations that appear in the inserter with their own name, icon and description, preconfigured with attributes and inner blocks.
A practical example: a testimonial
A client wants testimonials: a quote, a person’s name and their role, in a consistent layout with a particular background. Instead of building a custom block, register a variation of the Group block with preset inner blocks:
Editors now see “Testimonial” in the inserter. When they add it, they get a styled group with three placeholder paragraphs ready to fill in.
The isActive function tells the editor how to recognise the variation after insertion, so the block toolbar and List View show “Testimonial” rather than “Group”.
Registering variations in PHP
Since WordPress 6.5, you can also register variations server-side, using the get_block_type_variations filter. This is useful when variations depend on data, such as one variation for each custom post type:
Query loop variations like this are particularly useful. Editors insert “Latest case studies” and get a correctly configured query without touching any settings.
Variation scope
The scope property controls where a variation appears:
- inserter shows it in the block inserter
- block shows it in the placeholder when the block is first added, as with the Columns block’s layout choices
- transform shows it as an option to switch between variations in the block’s toolbar
Styles, variations, patterns or custom blocks?
These options overlap, so a rule of thumb helps.
- Block style: the block is right, it just needs a different look. Buttons, quotes, images, groups with a particular treatment.
- Block variation: the block is right, but it needs a specific starting configuration that editors will use often, and it deserves its own name in the inserter.
- Pattern: you need a larger arrangement of several blocks, such as a full hero section or pricing table, that editors can modify freely after inserting.
- Custom block: you need markup, behaviour or settings that no core block offers, such as dynamic data from an API or complex interactive features.
In my projects, styles and variations handle a surprising share of client requests. Custom blocks are reserved for genuinely custom functionality.
Keeping things maintainable
A few habits help as these accumulate:
- Keep all style and variation registrations in one file or folder, so they’re easy to find.
- Use theme.json presets in styles so they follow design changes automatically.
- Name things for their purpose, like “Callout” or “Testimonial”, rather than their appearance, like “Blue box”.
- Document available styles and variations for editors, even with a simple page in the admin or a pattern showing each one.
- Remove options you don’t want used, as well as adding ones you do.
Because styles and variations build on core blocks, they continue to benefit from every improvement WordPress makes to those blocks. Custom blocks have to be maintained by you. That alone is a strong reason to reach for styles and variations first.
A worked example from a real project
On a recent site for a training company, the brief included eleven “custom components” in the design file. The first instinct from the previous developer had been eleven custom blocks. When we went through them one by one, the picture was quite different.
Three were simply buttons with different treatments: a solid button, a pill-shaped button and a text link with an arrow. Those became two block styles on the core Button block, plus one removed core style that didn’t fit the design. Two were boxes with coloured backgrounds and a left border, used for tips and warnings. They became Group block styles defined in JSON, using theme presets, so they’d follow any future colour changes.
The testimonial, the course card and the instructor profile became block variations of the Group block with preset inner blocks, so editors could insert them by name. The “upcoming courses” list became a Query Loop variation filtered to the course post type. Only two components needed custom blocks: a course schedule that pulled dates from an external booking system and an interactive price calculator.
Eleven planned custom blocks became two. The project shipped faster, the editors found everything in the inserter under clear names, and when WordPress later improved the core Group and Button blocks, the site picked up those improvements automatically. That’s the practical case for reaching for styles and variations first.
Teaching editors what’s available
Styles and variations only help if editors know they exist. Block styles appear in the sidebar’s Styles panel, which some editors never open. Variations appear in the inserter, but only if editors search for them.
A short internal guide helps: a single page listing each style and variation with a screenshot and a sentence explaining when to use it. Some teams create a hidden “style guide” page on the site itself, built from the real blocks, so editors can see everything in context. Revisit it whenever you add or remove an option, and editors will use the system the way it was designed. Reach for WordPress block styles and variations first, and save custom blocks for the problems that truly need them.
Frequently asked questions
Can I add a block style to a third-party block?
Yes, using the block’s name, such as woocommerce/product-button. Check that the block’s markup supports the CSS you need.
Do block styles work in classic themes?
Yes. register_block_style works in any theme that uses the block editor. JSON style variations require a block theme.
Will my variations survive WordPress updates?
Generally yes, because they’re built on core block APIs. If a core block’s attributes change significantly, a variation may need adjusting, but that’s rare.
Can a variation lock its inner blocks?
Yes. Add templateLock to the attributes, or set lock attributes on individual inner blocks, to prevent editors from removing or moving them.
