5 Tips for Styling the Block Editor in Classic or Hybrid Themes

Back in the day when I worked as a theme developer for WordPress.com, I had to include editor styles in any themes I created. And I always disliked the process, because it was tedious, and error-prone.

So when I switched to building client projects, I was happy to leave this behind. In fact I’ve never written an editor stylesheet for any client project using the classic editor.

But the introduction of the block editor has changed this. Users now expect the editor to look like the frontend. Or at least be close to it. And in a block theme, it’s not an issue. You use Global Styles and Settings and a few block styles, and both the frontend and the editor look great.

However when adding block editor support to a classic theme, we don’t get to benefit from these block theme advantages. And creating a separate set of editor styles is not a choice.

So how can we get decent editor styles without duplicate work? This article will show you how.

Tip 1: Add a theme.json

While WordPress offers ways to use PHP to configure the block editor customization options, these are too limited to be useful.

So the first step is to add a theme.json file to the theme. It can start out basic, with just the version and the schema:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json"
    "version": 3
}

This turns the classic theme into a hybrid theme. In this video explain the importance of using theme.json in hybrid themes.

Once you’ve added the theme.json file, there are three things you need to do.

Set the content size

Choose the default width of the content editor as the size:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json"
    "version": 3,
    "settings" : {
        "layout": {
            "contentSize": "650px"
        }
    }
}

You are not limited to using pixels. Any valid value in CSS is also valid here.

Disable the Template Editor

WordPress enables the Template Editor by default whenever you add a theme.json file. But if a theme doesn’t have proper support for this editor, it not only looks awful, but it also isn’t very useful.

Therefore I always recommend turning it off:

<?php
function wpdc_disable_template_editor() {
    remove_theme_support( 'block-templates' );
}
add_action( 'after_setup_theme', 'wpdc_disable_template_editor' );

Disable block widgets

If the classic theme does not support widgets, then there’s nothing to worry about. But if it does support them, then WordPress will enable block widgets.

This disables them:

<?php
function wpdc_disable_block_widgets() {
    remove_theme_support( 'widgets-block-editor' );
}
add_action( 'after_setup_theme', 'wpdc_disable_block_widgets' );

Tip 2: Curate the block editor experience

Classic WordPress and modern WordPress have a fundamentally different approach to exposing customization options. Whereas WordPress previously didn’t offer much if anything out of the box, modern WordPress gives users a whole set of tools through the block editor.

While I’m absolutely not against giving users more customization options, it’s important to focus on one thing at a time. So what I recommend is to turn everything off starting out. Essentially you’d be creating a block-based version of the classic editor.

There are two important tasks to do:

Use the settings key in theme.json to remove all customization options from the blocks.
Remove all blocks that do not fit with the content. That goes from Theme blocks, to Widget blocks to possibly Design blocks. I recommend an allow list approach.

This gets you a clean slate to start working from. And you can always add back features and blocks later.

Tip 3: Use add_editor_style to enqueue styles in the backend

The most straightforward way to style the block editor is to enqueue the main stylesheet in the admin. So that means taking the entire frontend stylesheet (style.css or similar), and enqueue it on block editor pages in the backend.

So how to achieve this? There are three ways to add a CSS stylesheet to style the block editor.

The first is to use enqueue_block_editor_assets, an action that fires on these admin pages right before the code that bootstraps the block editor. The issue with this hook is that it’s not very future-proof.

The second is to use enqueue_block_assets. This hook is used to enqueue block assets, and not block editor assets. Therefore it fires both on the frontend, and the backend, but you can target the backend with an is_admin() check.

The main issue you got to deal with is your custom styles impacting the rest of the admin interface. On most sites, the editor is not in an iframe, instead it is part of the rest of WP Admin.

Therefore any styles that are not scoped to .block-editor-wrapper will impact all of WP Admin. Typically this are styles tied to body, or HTML tags such as p, a, and so on.

You can work around this using a CSS build pipeline that transforms your original styles during the build process. Or you can use WordPress’ builtin on the fly transformation.

Which brings us to the third option: use the add_editor_style function. With the block editor enabled, any CSS added this way is inlined into the block editor, and all styles are scoped to .editor-styles-wrapper.

<?php
function wpdc_add_editor_styles() {
    add_theme_support( 'editor-styles' );
    
    add_editor_style( 'style.css' );
}
add_action( 'after_setup_theme', 'wpdc_add_editor_styles' );

This is the safest way to get these styles into the editor. But once we are over this hurdle, we need to look at optimizing the results in the editor.

Tip 4: Remove CSS resets

Our approaches to writing CSS evolve over time. The Twenty Twenty theme still uses a CSS reset, where as Twenty Twenty-One opts for the less destructive normalization approach.

While CSS resets do work fine on the frontend, including them in the editor can cause issues. Even when injected through add_editor_style().

My recommendation is to remove the CSS reset from the main stylesheet. This way you can still use the style.css as an editor stylesheet. And on the frontend you can enqueue the CSS reset first, and then the stylesheet afterwards. Yes, two requests are slower than one request, but the impact is minimal.

If the theme uses normalize.css or a similar approach, then you shouldn’t need to worry too much. In this case I’d recommend reviewing the normalize styles. Because you’ll find that you can get rid of most of these declarations.

Tip 5: Remove font-size: 62.5% hack

This is one of these “we didn’t know any better back then” approaches to CSS that haunts themes to this day. Even themes like Twenty Twenty use this senseless trick. And all to avoid doing rem size calculations.

I’m talking about this:

html {
    font-size: 62.5%; /* 1rem = 10px */
}

This allows you to write something like 1.8rem in your CSS, and it works out to 18px. The issue that we are facing is that in the block editor context, all the CSS relies on the default font size being a 100%.

Here there is unfortunately no simple, quick fix. You need to remove the 62.5% calculation, and then change all of the rem sizes to use a base of 16 pixels, instead of 10 pixels.

If you are using Sass, you can use a function like this to facilitate the job:

@function toRem($value) {
    $remValue: ($value / 16) + rem; 

    @return $remValue;
}

In general though, I’d just rely on a plain search-replace, rather than introducing more complexity.

Where to go from here?

If you went through the steps outlined above, you now should have a decent first set of editor styles. You also have a hybrid theme, with a theme.json file that is ready to be extended.

The next logical step is to use theme.json as much as possible for styling. Previously you need to write these styles manually. But now you can use the Site Editor to create them visually, and then you can export them to theme.json using the Create Block plugin.

I talked about how to enable the Site Editor in a Classic theme in a previous article. It is a bit of a hack, but still a lot better than having to manually write styles in JSON.