How to Add CSS Classes to WordPress Blocks

Add a class in the block settings

Start in the post or page editor. Select the block you want to target. If the right sidebar is hidden, click the Settings button near Save or Publish, select the Block tab, and expand Advanced. The current Advanced Settings overview documents that route and the Additional CSS class(es) control. ^[1]

Enter a class token such as wpshout-callout. For two labels, separate them with spaces: wpshout-callout wpshout-callout--quiet. Do not type a leading dot, class="wpshout-callout", curly braces, or a declaration such as color: red;. Those belong to CSS syntax, not this input.

The important mental model is simple: a custom class labels the block’s wrapper. It does not add color, padding, or any other style by itself. Block support for customClassName supplies the field for a block wrapper, and the documented default is enabled. ^[2] Save or update the page after adding the label, then style the saved markup.

If you maintain your own blocks, the wrapper is part of the contract. A static block needs useBlockProps.save() on its saved root element, while a server-rendered block needs get_block_wrapper_attributes() on its outer rendered element. Without that handoff, the editor may offer a support setting but the front end has nowhere reliable to receive its class. ^[3]

Write the CSS rule that uses it

Next, add the rule in the CSS location your site already uses. A small site may keep it in the theme’s custom CSS area, while a maintained site may use a child theme or a small site plugin. If you need a refresher on choosing that home, WPShout’s guide to WordPress custom CSS covers the practical options. Keep the class name specific enough that it describes the component, not a temporary color.

.wpshout-callout {
    border-left: 4px solid #2271b1;
    padding: 1rem;
    background: #f0f6fc;
}Code language: CSS (css)

The leading dot belongs in the selector here, not in the WordPress field. A prefixed name such as wpshout-callout reduces the chance of colliding with a theme or plugin class. If the result does not appear, inspect the published page rather than trusting the editor preview. Browser developer tools can confirm that the wrapper has your class, show which rule wins, and reveal a more specific competing selector. Clear relevant page, plugin, CDN, and browser caches before concluding the rule failed.

Keep the selector as narrow as the design requirement. .wpshout-callout is a good starting point because it targets only blocks carrying that class. A rule like .entry-content p reaches far more content and can affect old posts, a template part, or a pattern you did not mean to change. If a theme rule wins, understand why before raising specificity. A selector that is hard to override becomes somebody else’s maintenance problem later.

Custom styling still has to work for people navigating by keyboard or using assistive technology. Preserve visible focus, readable contrast, and the HTML meaning of the block. A class can make a link look like a button, but it should not turn a non-button element into an inaccessible fake control.

Know which blocks can use a class

Most ordinary content blocks expose the field, but it is not a promise that every block will. A block author can opt out, which is why the absence of Advanced settings is not necessarily an editor bug. The current core definitions for both the Shortcode block and the Custom HTML block set customClassName to false. ^{[4] [5]} For these blocks, style the output they generate through an appropriate template, shortcode, or CSS selector instead of expecting an instance class field.

For custom blocks, keep the wrapper behavior you implemented in mind. The class can reach the front end only if the saved or dynamic root receives the generated block properties. If a block has no meaningful outer element, do not force a wrapper merely to create a styling hook. Choose the markup deliberately, then make the styling interface match what the block can actually render.

Also inspect the correct element. Some blocks contain several nested elements, and a class placed on the wrapper does not automatically style every child. Start with the wrapper selector, then add a descendant selector only when the design really needs it, for example .wpshout-callout a for a link inside a callout. That makes the relationship explicit and avoids accidental styling of unrelated links.

Choose the right style scope

A custom class is useful when you want to target selected instances, such as a handful of callouts inside long articles. WordPress combines block markup, theme and block stylesheets, Global Styles, and user changes when it builds the front end. Local block changes can be represented by classes or inline styles, so the same visual result can have different ownership depending on the tool you choose. ^[6]

Use a block style variation when you want a repeatable visual choice that authors can select from the block’s own UI. Use Global Styles or Styles > Blocks when every instance of a block type should share a default. The Styles interface can set site-wide colors, typography, layout, and block-type defaults, so it is the wrong lever for a single exceptional paragraph. ^[7]

This distinction avoids specificity battles. A local selector can be deliberately narrow. A global block-type rule is broader by design. Before adding !important, inspect the cascade and decide whether the change really belongs to the one instance, the block type, or the theme’s design system.

A useful test is to ask what should happen when an editor adds the next block. If it should look the same everywhere, set a block-type default. If authors should choose between named designs, make a style variation. If only this one sentence, group, or callout needs the treatment, use a custom class. The smaller the intended scope, the smaller the selector and CSS change should be.

Patterns can expand the scope

Patterns add another scope question. If the block lives in a synced pattern, editing that pattern updates it everywhere the pattern is used. Detach the pattern first when you need a change on just one page. ^[8] That is often the safer choice than adding a class and then wondering why a footer, signup prompt, or repeated callout changed across the site.

For a deeper pattern workflow, see WPShout’s guide to WordPress block patterns. The useful rule is not to avoid classes. It is to identify whether you are editing an independent block, a shared pattern, or a site-wide default before you save.

Do not confuse classes with WordPress 7 Additional CSS

WordPress 7.0 added a second Advanced-panel feature called Custom CSS or Additional CSS for individual block instances. It is not a replacement label for the class field. It accepts declarations such as color: blue;, not a selector, and it is available only to users with the edit_css capability. WordPress generates a unique outer class and a scoped stylesheet for that one instance. ^[9]

Use that field for a truly local declaration when your role and editorial rules allow it. Use Additional CSS class(es) when you want a stable, readable hook that can be styled and reused through your normal stylesheet. Keep the two inputs separate: class tokens in the class field, declarations in the per-instance CSS field.

That difference is useful during handoff, too. A class name communicates intent to the next developer and can be searched across a codebase. A per-instance declaration is tied to one saved block and is appropriate when the exception should stay there. Neither option removes the need to test the published page after theme, plugin, or cache changes.

For most editorial work, the final check is brief: select the right block, add a clean token, save, load the front end, inspect the wrapper, and verify focus and contrast. That sequence catches the common mistakes without turning a small styling task into a fragile workaround.