Block Styles and Variations

There’s a difference between styles (visual variants of the same block) and variations (preset configurations that appear as separate inserter items).

Block styles — visual variants

Styles add a class to the block based on user selection. Register them in src/index.js:

import { registerBlockStyle } from '@wordpress/blocks';

registerBlockStyle('my-first-block/callout', [
  { name: 'boxed',    label: 'Boxed',    isDefault: true },
  { name: 'plain',    label: 'Plain' },
  { name: 'filled',   label: 'Filled' },
  { name: 'outlined', label: 'Outlined' },
]);

Each style adds is-style-{name} to the block’s className. Then style them in CSS:

.my-callout {
  &.is-style-boxed    { border: 1px solid; padding: 1rem; }
  &.is-style-plain    { border: none; padding: 0.5rem 0; }
  &.is-style-filled   { background: currentColor; color: white; padding: 1rem; }
  &.is-style-outlined { border: 2px solid currentColor; background: transparent; }
}

Users see a “Styles” panel in the inspector with a thumbnail per style.

Block variations — preset configurations

Variations make pre-configured versions of your block appear in the inserter as if they were separate blocks. Perfect for “Tip Callout”, “Warning Callout”, “Error Callout” without duplicating the block:

import { registerBlockVariation } from '@wordpress/blocks';

registerBlockVariation('my-first-block/callout', [
  {
    name: 'callout-tip',
    title: 'Tip Callout',
    description: 'A green tip box.',
    icon: 'lightbulb',
    attributes: { calloutType: 'tip', title: 'Tip' },
    scope: ['inserter'],
  },
  {
    name: 'callout-warning',
    title: 'Warning Callout',
    description: 'An amber warning box.',
    icon: 'warning',
    attributes: { calloutType: 'warning', title: 'Heads up' },
    scope: ['inserter'],
  },
  {
    name: 'callout-error',
    title: 'Error Callout',
    description: 'A red error box.',
    icon: 'dismiss',
    attributes: { calloutType: 'error', title: 'Error' },
    scope: ['inserter'],
  },
]);

The scope field controls where variations appear:

• 'inserter' — show in the block inserter as separate items
• 'transform' — show in the block transform menu (convert from another block)
• 'block' — show in the block’s “Variation” picker (when no attributes are set)

Styles vs variations — when to use which

Need	Use
Multiple visual treatments of the same data	Style
Multiple insertable presets with different defaults	Variation
Both	Both (they compose)

For our Callout: variations expose “Tip / Warning / Error” as separate inserter items (better discoverability). Styles let users switch between “Boxed / Filled / Outlined” treatments (same data, different look).

Verification

After registering both, hit the + in the editor:

• Search “callout” → see “Callout”, “Tip Callout”, “Warning Callout”, “Error Callout”
• Insert “Tip Callout” → block appears pre-configured with calloutType: 'tip' and title: 'Tip'
• Select any callout → inspector shows “Styles” panel with 4 thumbnails

What’s next

Part 8 covers block patterns — pre-designed combinations of multiple blocks users can drop in. Unlike variations, patterns can include nested structure and content.