Skip to main content

May 24th, 2023

Disabling WordPress Block Formatting Controls via Theme.json

If you work with the block editor, you may have noticed just how many formatting controls are offered to influence a specific block’s appearance within it. These formatting controls unfortunately introduce a lot of opportunity for inconsistencies in styling when left in client projects, as well as can be overwhelming to those clients who aren’t designers or developers.

Fortunately, WordPress does provide a route to modify what controls appear in the editor and the best way to do that is using something called the theme.json file.

What is Theme.json?

Theme.json is a configuration file to control various theme settings and blocks within the block editor. It was rolled out in WordPress 5.8. If your theme is using a theme.json file, you would see it in the root folder of your active theme. You do not need to be using full-site editing in order to use theme.json.

Implementing Theme.json

If your theme does not use theme.json yet, it’s not advised to just drop the file into a production theme folder without testing first. Depending on how you build in the block editor, themes may need additional adjustments and could see visual changes within the block editor once implementing a theme.json file. If you use a block-based builder like GeneratePress or Kadence or an existing theme, check with their support or any documentation to see to what degree theme.json is supported before attempting to implement it. For existing projects, test theme.json on a local or staging environment. For new projects, if it’s possible to work its inclusion into your build process, it’s worth considering doing so as the importance and capabilities of the theme.json file only continue to grow.

When using theme.json, the settings within it do replace a handful of items that were addressed with add_theme_support functions, which WordPress outlines here. If you’re starting to use theme.json, familiarize yourself with these items to ensure you’re not duplicating declarations here in any kind of starter theme set up is recommended.

Once you get your settings how you’d like them within theme.json, you’ll find a great deal of it often stays consistent project-to-project in terms of what controls you’re disabling. It takes the longest to find the initial set up that works best for you but projects from there on out aren’t starting from scratch. To start my own configuration, I’m usually starting with the default controls I consistently disable project-to-project and swapping out project-specific variables like the color palette, font sizes, font families, and layout, to name a few. If you implement a theme.json and don’t set layout size in the file, you may notice visual changes in the editor width, as well as issues with align wide and similar working as anticipated. If you don’t declare a font through the editor, you may notice the editor often falls back to a default serif font.

Theme.json Structure

A theme.json file goes in the root theme folder. Once it exists, WordPress will read it automatically. At its core, theme.json follows this structure:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {},
  "styles": {},
  "customTemplates": {},
  "patterns": {},
  "templateParts": {}
}

$schema is not required in the file, but if you use an editor like Visual Studio Code or another editor that supports JSON schema, it’ll provide things like tooltips, autocomplete, and validation within the file so it’s incredibly helpful.

Empty data sets also aren’t needed in the file so if you’re not using something, like customTemplates, it can be removed. In terms of disabling formatting controls, the focus of this post but the tip of the iceberg in terms of what you can do within theme.json, we’ll be concentrating on the “settings” section of the theme.json file.

In all the examples below to disable controls via this file, the theme.json snippet is given showing where it falls in this structure individually for clarity on placement. If you’re disabling multiple controls, like you want to disable both colors and border radius, you wouldn’t use the full example of each. You’d merge the examples together so something like your block settings section has both a color and a border section.

Global Disabling of Formatting Controls

For many formatting controls, you have the ability to disable the control globally, as well as at the individual block level. Typography controls like customFontSize and fontStyle are great examples of this. If you make them false globally, you don’t need to also declare them as false within a particular block.

Whatever you set globally should be what a majority of your blocks should adhere to so you’re only left overriding a few styles at the block level.

Disabling Typography Controls in WordPress Blocks

When it comes to items like custom font sizes, line height control, and more, those controls can be disabled across the board if you instead want to take the reins and determine how these items are handled in your theme stylesheet or comparable. You can pick and choose which to disable globally or at the block level.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "typography": {
      "customFontSize": false,
      "lineHeight": false,
      "dropCap": false,
      "fluid": false,
      "fontStyle": false,
      "fontWeight": false,
      "letterSpacing": false,
      "textDecoration": false,
      "textTransform": false,
      "fontSizes": [],
      "fontFamilies": []
    }
  }
}

Disabling Color Controls in WordPress Blocks

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color":{
      "text": false,
      "background": false,
      "customDuotone": false,
      "customGradient": false,
      "defaultDuotone": false,
      "defaultGradients": false,
      "duotone": [],
      "gradients": []
    }
  }
}

If you’re seeing a color control persist in the block editor even after declaring it false in the theme.json file, clicking into the control to see what’s appearing can offer insight on what additional controls may need to be disabled as sometimes multiple options need to be disabled to fully remove a setting. For instance, if you just set background to false, you’ll see the control to set a background color persists and if you open it, you’ll see gradients inside it, suggesting gradients also need to be disabled to fully disable the control.

Disabling a Specific WordPress Block’s Controls

Disable Color Controls for a Specific WordPress Block

The following disables all color controls if they’re enabled globally. If you’ve disabled a color control like defaultGradients globally, you can remove it as it’s unnecessary to duplicate. It is not likely that you would be enabling or disabling this amount of settings at the individual block level, but they’re provided here nonetheless. It’s far more common to make a majority of choices globally and then block-specific areas in this file are more limited. Make sure you’re not unnecessarily duplicating global settings or declaring the same setting as true or false in a bunch of blocks individually versus making a more efficient global choice.

You’ll see the block used in the example is the button block (core/button). If you wish to modify color controls for a different block, simple replace core/button with the name of the block you’d instead like to modify. You can view available blocks to modify here. All core blocks have “core/” before the name so it would be something like core/columns, core/quote, core/list, etc.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "blocks": {
      "core/button": {
        "color":{
          "text": false,
          "background": false,
          "customDuotone": false,
          "customGradient": false,
          "defaultDuotone": false,
          "defaultGradients": false,
          "duotone": [],
          "gradients": []
        }
      }
    }
  }
}

Limit WordPress Block Color Palette

You may wish to allow color control but want to limit the palette specific to a block so a client can choose from a fixed selection of color options. Again, swap the core/button name out with a different block name if you so choose.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "blocks": {
      "core/button": {
        "color": {
          "palette": [
            {
              "slug": "black",
              "color": "#000",
              "name": "Black"
            },
            {
              "slug": "white",
              "color": "#FFF",
              "name": "White"
            }
          ]
        }
      }
    }
  }
}

Disable Typography Controls for WordPress Blocks

Core/button would be swapped out with the name of the block you want to adjust.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "blocks": {
      "core/button": {
        "typography": {
          "customFontSize": false,
          "lineHeight": false,
          "dropCap": false,
          "fluid": false,
          "fontStyle": false,
          "fontWeight": false,
          "letterSpacing": false,
          "textDecoration": false,
          "textTransform": false,
          "fontSizes": [],
          "fontFamilies": []
        }
      }
    }
  }
}

Disable Spacing Controls for WordPress Blocks

Core/button would be swapped out with the name of the block you want to adjust.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "blocks": {
      "core/button": {
        "spacing":{
          "margin": false,
          "padding": false
        }
      }
    }
  }
}

Disable Border Radius for WordPress Blocks

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "blocks": {
      "core/button": {
        "border": {
          "radius": false
        }
      }
    }
  }
}

Troubleshooting

If you’re struggling to see your theme.json settings reflected in WordPress, a handy PHP function you can use to see what settings WordPress is pulling is wp_get_global_settings(). By viewing what that function returns, you can see if any of your theme.json settings are being found to offer insight on whether the problem may be something like formatting to where none of your theme.json settings are being read correctly.

JSON is picky and so much as a misplaced comma can cause settings inside the file to not be read correctly. It’s highly advised you use either a linter that does JSON validation within your code editor or there are also online tools, such as jsonlint.com that can be used to check formatting.

Alternative Approaches to Theme.json for Disabling Block Editor Controls

If you’re not able to use theme.json, there are still controls that can be disabled via add_theme_support, like disabling custom font sizes, custom gradients, and others. You just have far less control than you have if you are able to use a theme.json file.

Additional Insights

Get the latest in your inbox