How to Register Block Styles in WordPress

WordPress block styles add named visual choices to an existing block. Selecting one adds an is-style-{name} class to the block wrapper. Use a block style when the markup and behavior stay the same and only the presentation changes.

Recommendation: Register styles in PHP when a theme or plugin needs reliable server-side registration and attached style assets. Use JavaScript when editor-side conditions or client registration are necessary. Use theme.json to define the design values for registered variations, not as a substitute for every registration method.

Block style, block variation, pattern, or new block?

• Use a block style for the same block and markup with a different appearance.
• Use a block variation for a preset block configuration, attributes, inner blocks, or a specialized starting state.
• Use a pattern for a reusable arrangement of several blocks.
• Create a custom block when the content model, behavior, data, or semantic output is genuinely different.

Register a block style with PHP

Register styles on init. Include a translated label and provide CSS through inline_style, a registered style_handle, or supported style_data.

function mg_register_block_styles() {
    register_block_style(
        'core/quote',
        array(
            'name'         => 'brand-callout',
            'label'        => __( 'Brand callout', 'mg-site' ),
            'style_handle' => 'mg-block-styles',
        )
    );
}
add_action( 'init', 'mg_register_block_styles' );

Register the stylesheet handle before it is referenced. Scope selectors to both the block and style class so the rule does not leak:

.wp-block-quote.is-style-brand-callout {
    border-inline-start: 0.25rem solid var(--wp--preset--color--brand);
    padding-inline-start: var(--wp--preset--spacing--40);
}

Use inline_style for a small variation

register_block_style(
    'core/quote',
    array(
        'name'         => 'compact',
        'label'        => __( 'Compact', 'mg-site' ),
        'inline_style' => '.wp-block-quote.is-style-compact{padding:1rem}',
    )
);

Inline CSS is convenient for a tiny rule. A versioned stylesheet is easier to cache, audit, and maintain when styles grow or include responsive and state rules.

Register a style with JavaScript

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

registerBlockStyle( 'core/quote', {
    name: 'brand-callout',
    label: 'Brand callout',
} );

Enqueue the built script only in the block editor and declare the generated dependencies. The stylesheet must still load in both the editor and frontend. JavaScript registration is useful for editor logic, but PHP often gives a simpler shared foundation.

Block style variations and theme.json

Modern WordPress supports styling registered block style variations through theme.json-compatible data. The exact capabilities depend on the target WordPress version. Keep a documented minimum version and test the Site Editor, post editor, templates, patterns, and frontend.

Do not copy examples that place arbitrary registration objects into unsupported theme.json paths. Registration and style data are related but distinct concerns. Follow the current Block Editor Handbook for the WordPress versions your product supports.

Unregister a block style

Server-side unregister_block_style() only removes a style registered on the server. Client-side styles require unregisterBlockStyle(). For JavaScript, run after the original registration to avoid a race condition.

wp.domReady( function () {
    wp.blocks.unregisterBlockStyle( 'core/quote', 'plain' );
} );

Removing an option does not rewrite existing content. Old posts may retain the is-style-plain class. Keep compatible CSS or migrate content before removing support.

Load styles in the editor and frontend

• Test the style selector in the post editor and Site Editor.
• Confirm the selected style renders the same on the frontend.
• Support left-to-right and right-to-left layouts with logical properties where possible.
• Check keyboard focus, forced colors, contrast, zoom, and reduced motion.
• Avoid selectors that rely on fragile editor-only markup.
• Version assets and verify caching after deployment.

Enterprise design-system guidance

• Use human labels and stable machine names. Renaming a slug changes the saved class contract.
• Limit options to approved and meaningful variations.
• Connect colors, spacing, typography, and borders to design tokens.
• Document when each variation should be used and provide editorial examples.
• Review accessibility before a style enters the shared library.
• Track ownership, supported WordPress versions, deprecation, and migration.
• Test styles inside patterns, templates, nested blocks, and localized content.

Common mistakes

• Using a style when the block needs different semantics or behavior
• Loading CSS only in the editor or only on the frontend
• Registering the same name in multiple packages
• Unregistering before core or plugin registration finishes
• Removing CSS while published content still uses the old class
• Hard-coding colors instead of using design tokens
• Offering so many options that editors cannot maintain consistency

For a governed component library, see enterprise WordPress design systems or custom WordPress theme development.

Primary sources

• WordPress Block Styles API
• register_block_style reference
• unregister_block_style reference

Frequently asked questions