How to add custom CSS in a WordPress block theme

In classic themes, custom CSS lives in the Customizer, under “Additional CSS”. Block themes don’t show the Customizer in the admin menu, so the first time you go looking for it, it can seem like it’s gone entirely. It isn’t. It just packed up and moved to a new home in the Site Editor.

Before we open it, though, a recommendation: never do in CSS what you can do in the Site Editor. Colors, fonts, spacing, borders and shadows all have controls under “Styles”, and changes you make there show up in the editor, are saved with the rest of your styles, and can easily be adjusted by anyone who edits the site after you. It’s also easy to override those changes on any individual block you edit on a post or page, while your own CSS might be more difficult to override.

CSS is for the things the controls in the Site Editor can’t do. Fortunately, that list is growing shorter with every WordPress release. In 7.2, we’re finally getting text shadow controls, for example.

In this tutorial, we’ll take a look at the places you can add CSS in a block theme, from the whole site down to a single block type, and the options you have if you’re building the theme yourself.

Adding CSS to your whole site

The Site Editor’s version of “Additional CSS” is a bit hidden, but it works the same way as the one in the Customizer:

  1. Go to “Appearance” → “Editor”, and click “Styles”.
  2. Click the three dots at the top of the Styles panel, and select “Additional CSS”.
  3. Add your CSS, and click “Save”.

The CSS you add to the field is loaded on every page of your site, and in the editor too, so you can see the result while you write. For example, to make links to a section on the same page scroll smoothly instead of jumping straight to it:

@media (prefers-reduced-motion: no-preference) {
html {
scroll-behavior: smooth;
}
}

Unfortunately, the new editor is still a regression from the Customizer one in a few key ways. There’s no syntax highlighting, no tab indentation and no autocomplete. Hopefully we don’t have to wait too long for those features to arrive.

The CSS is saved with your other style changes, so it’s tied to the theme you’re using. If you switch themes, it won’t come along, which is usually what you want.

Adding CSS to a single block type

If your CSS is only meant for one type of block, like all paragraphs or all buttons, you can add it to that block instead:

  1. In “Styles”, click “Blocks” and select the block.
  2. Scroll to the bottom of the panel and open “Advanced”.
  3. Add your CSS in the “Additional CSS” field.

Here, you don’t need a selector. WordPress adds the block’s own selector for you, so you only write the properties and values. To style something inside the block, use & for the block itself:

letter-spacing: 0.01em;
& a {
text-underline-offset: 0.2em;
}

Added to the Paragraph block, the first line applies to every paragraph, and the second to links inside them. Keeping the CSS with the block it belongs to lets the site-wide field stay short, but there’s a catch: the list of blocks in “Styles” doesn’t show which ones have CSS added to them. Spread it across enough blocks, and it’s easy to lose track of where you put what, so keep a note if you add CSS to more than a block or two.

If you’re building the theme

The two fields in the Site Editor have counterparts in theme.json, which is handy if you want the CSS to ship with your theme or child theme. Add it as a css string in styles, either at the top level or for a specific block:

{
"version": 3,
"styles": {
"css": "@media (prefers-reduced-motion: no-preference) { html { scroll-behavior: smooth; } }",
"blocks": {
"core/paragraph": {
"css": "letter-spacing: 0.01em; & a { text-underline-offset: 0.2em; }"
}
}
}
}

That works for a few lines, but CSS in a JSON string gets hard to read quickly. For that reason, I rarely use the css property in theme.json, if ever. This is a matter of personal preference, but I view the css property as a backup for the CSS users add in the Site Editor – not a field developers are meant to edit directly. The style.css file for this site has about 300 lines of CSS. Editing all of that on a single line in theme.json would be madness.

For anything longer than a few lines, put it in your theme’s style.css, or in separate stylesheets for individual blocks, and load them with a few lines in functions.php:

/**
* Loads the theme stylesheet on the front end and in the editor.
*/
function my_theme_styles() {
wp_enqueue_style(
'my-theme-style',
get_stylesheet_uri(),
array(),
wp_get_theme()->get( 'Version' )
);
}
add_action( 'enqueue_block_assets', 'my_theme_styles' );
/**
* Loads a stylesheet for the Paragraph block, only on pages that use it.
*/
function my_theme_block_styles() {
wp_enqueue_block_style(
'core/paragraph',
array(
'handle' => 'my-theme-paragraph',
'src' => get_theme_file_uri( 'assets/css/blocks/paragraph.css' ),
'path' => get_theme_file_path( 'assets/css/blocks/paragraph.css' ),
'ver' => wp_get_theme()->get( 'Version' ),
)
);
}
add_action( 'init', 'my_theme_block_styles' );

The first function loads style.css both on the front end and in the editor, so what you see while editing matches your site. WordPress doesn’t load style.css on its own, so without it, the file only holds the theme’s name and details.

The second one matches the per-block CSS from earlier: it gives the Paragraph block its own stylesheet, which WordPress only loads on pages where the block is used, and in the editor. The CSS goes in assets/css/blocks/paragraph.css in your theme, with the block’s class as the selector, like .wp-block-paragraph. Small stylesheets like this are usually added inline in the page rather than loaded as a separate file, so splitting your CSS up by block doesn’t cost you extra requests.

The downside of including CSS in stylesheets is that you can’t edit those styles directly in the Site Editor. If you’re building sites for clients, that could also be a blessing. CSS included in theme.json can be modified or removed entirely by your client, while enqueued stylesheets are protected as long as the client doesn’t use the Theme File Editor (which displays a prominent warning, and can be disabled), or edits the file directly with an SFTP client.

Which one to use

  • If there’s a control for it under “Styles”, use the control.
  • For a few lines that affect the whole site, use “Additional CSS” in the Styles menu.
  • For CSS that only applies to one type of block, add it to that block under “Blocks”.
  • If you’re building the theme, use theme.json only for a line or two, and style.css or block stylesheets for everything else.

One thing to keep in mind with the two fields in the Site Editor: the CSS is saved with your style changes in the database, not in the theme. If you or someone else clicks “Reset styles” in the Styles menu, it’s removed along with everything else, so keep a copy of anything you’d hate to write again.