How to Define Block Settings in theme.json to Control the Editor Experience

The theme.json file gives block theme developers precise control over what the editor exposes to content creators. The settings.blocks section takes this further, letting you configure individual blocks differently from your global defaults. This article covers how to use per-block settings to craft an editor experience that is both powerful for developers and intuitive for clients.

---

What Is the settings.blocks Section?

Your theme.json file has a top-level settings object that applies globally to all blocks. But within that same settings object, there is a nested blocks key that lets you override those global defaults on a per-block basis. If you are new to the overall theme.json structure, mastering theme.json as a complete block theme configuration guide covers the full schema before you get into per-block specifics.

The structure looks like this:

Any setting you place inside settings.blocks.{block-name} applies only to that block. It can either extend your global settings (by adding options that are not globally defined) or restrict them (by disabling features that are on globally).

Global Settings vs Per-Block Settings

Before diving into per-block configuration, it helps to understand the inheritance model. WordPress applies settings in this order:

• Core defaults, what WordPress ships with out of the box
• Global theme settings, your top-level settings in theme.json, including things like the global color palette and typography scale you configure when you configure global styles in theme.json for consistent block theme design
• Per-block settings, settings.blocks.{block-name} overrides

Per-block settings always win. If you globally enable background color for all blocks, you can then disable it for core/paragraph specifically using settings.blocks. The override flows in one direction, block-level always beats global.

Controlling Color Settings Per Block

Color controls are among the most common things to restrict in a client theme. Left unconfigured, editors can choose any text color, any background color, and apply gradients, which quickly leads to off-brand designs. The settings.blocks section lets you set clear limits.

Disabling Background Color for Paragraphs

By default, the paragraph block offers a background color picker. You can remove it entirely for that block while keeping it for other blocks like core/group:

With this configuration, group blocks can still have background colors, but paragraphs cannot. This is the right call for most content-focused sites, paragraph background colors rarely look good and editors tend to misuse them.

Restricting the Color Palette to Specific Blocks

You can define a completely different color palette for a specific block. This is useful when a button block should only use your brand’s primary colors, not the full site palette:

Setting custom: false removes the color picker entirely, so the editor can only choose from the defined palette colors. Combined with a restricted palette, this keeps buttons on-brand without any extra effort from the content creator.

Disabling Gradients for Specific Blocks

Gradients can look great on cover blocks but out of place on headings. Disable them selectively:

---

Controlling Typography Settings Per Block

Typography controls are where per-block settings shine brightest. You probably want different font size ranges for headings versus paragraphs, and you may want to prevent editors from changing the font family on certain blocks entirely.

Defining Custom Font Size Scales Per Block

A common need: headings get a range of large sizes, body text gets a modest set. Instead of one shared scale that looks overwhelming in the inspector, define block-specific scales:

Now paragraph blocks show a compact 3-size scale, while heading blocks show a 4-size scale suited for display text. Neither allows typing a custom size, which keeps the design system enforced.

Restricting Font Families Per Block

If your site uses one font for headings and another for body copy, you can lock each block to its intended font:

With only one font available per block, the font family dropdown either shows a single locked option or disappears from the inspector, depending on how the block renders the control. This keeps your typographic hierarchy intact no matter who is editing.

Disabling Line Height and Letter Spacing Controls

Fine-grained controls like line height and letter spacing give editors the power to break your vertical rhythm. Disable them for blocks where they should not be touched:

---

Using appearanceTools as a Shorthand

WordPress introduced appearanceTools as a convenience shorthand. Setting it to true globally enables a bundle of UI controls at once, instead of enabling each one individually:

This single flag enables the following settings when they are not already defined:

Setting Group	Controls Enabled
border	color, radius, style, width
color	background, link, text
dimensions	minHeight
position	sticky
spacing	blockGap, margin, padding
typography	lineHeight

The key thing to understand: appearanceTools: true at the global level does not prevent you from disabling specific controls at the block level. You can use it as a fast way to turn everything on, then use settings.blocks to selectively turn things off per block.

This is the recommended approach for most themes: open everything up globally with appearanceTools, then close off specific controls for blocks where they cause design problems.

Configuring Spacing and Layout Per Block

Spacing is another area where per-block control pays off. You may want editors to control padding on group blocks but not on paragraphs. Or you may need different spacing scale options for different block types.

Custom Spacing Scale Per Block

The global spacing scale uses WordPress’s default steps or a custom set you define. You can override this for individual blocks. The spacing scale is defined as an array of size presets:

Group blocks get a spacious set of padding options suited for section layouts. Paragraphs get no spacing controls at all, their spacing should come from the parent container or theme stylesheets, not from individual block overrides.

Controlling Layout Settings Per Block

Layout settings control whether a block supports content width constraints and the inner block gap. The core/group block is the primary block where these matter:

Setting allowEditing: false on core/cover hides the layout controls from that block’s inspector, preventing editors from changing how the cover’s inner blocks are arranged. This is useful when your cover block template has a specific design that should not be touched.

---

Border Controls Per Block

Border controls work the same way, you can enable full border options on some blocks and disable them on others:

Images get rounded corners but no manual border controls. Buttons get radius and color options. Paragraphs get no border controls. This keeps your design system consistent without relying on editors to make the right choice.

Restricting the Editor for Client Projects

When building themes for clients who are not designers or developers, a locked-down editor is often more helpful than a fully open one. Here is a practical settings.blocks configuration for a typical business website where the client manages blog posts and landing page sections:

This configuration strips out controls that clients do not need and that would cause design issues if used incorrectly. The editor still works, clients can write content, pick from the defined color palette, and choose from the type scale, but they cannot break the site’s visual design. Once your editor is locked down, creating custom block patterns is a natural next step, it lets you pre-build the complex layouts clients need without requiring them to build from scratch.

Enabling Settings for Third-Party Blocks

The settings.blocks section works with any block, not just core blocks. Plugin blocks that declare support for theme.json configuration will respect your overrides. For example, if you use a plugin that registers a my-plugin/hero block:

Whether a block respects these settings depends on what block supports it has registered in its PHP or JavaScript code. Blocks that use useSettings (formerly useSetting) from @wordpress/block-editor will pick up your theme.json configuration automatically. Blocks that hardcode their own controls may not.

Custom Block Styles vs Per-Block Settings

It is worth clarifying what settings.blocks does versus styles.blocks. These are two different sections in theme.json with distinct purposes:

Section	Purpose	Example
settings.blocks	Controls what UI options the block shows in the editor inspector	Disable the background color picker for paragraphs
styles.blocks	Applies CSS styles to blocks on the frontend and in the editor	Set default paragraph font size to 1.125rem

You often need both. Use settings.blocks to restrict what editors can change. Use styles.blocks to set the default appearance when those settings are left at their defaults. Together they give you full control over both the authoring experience and the rendered output.

---

Debugging Per-Block Settings in the Editor

When a per-block setting does not seem to be taking effect, there are a few things to check.

1. Validate Your JSON

A single syntax error in theme.json causes WordPress to silently ignore the entire file and fall back to defaults. Use a JSON validator or your editor’s linting tools to check for missing commas, trailing commas, or mismatched brackets before testing in the editor.

2. Clear the Theme.json Cache

WordPress caches the resolved theme.json data. During development, use WP-CLI to flush it:

Or visit the WordPress admin with ?theme_json_cache=0 appended to the URL (this does not permanently disable caching, but forces a fresh read for that request).

3. Verify Block Name Spelling

Block names in settings.blocks must match exactly what the block is registered with. Use the Block Directory in /wp-admin/tools.php?page=block-directory or check the block’s block.json file to confirm its registered name. A common mistake is using core/buttons (plural) when you meant core/button (singular), or vice versa.

4. Check Block Support Registration

Per-block settings in theme.json only affect controls that the block has declared support for. If a block does not declare supports.color.background in its block.json, disabling it in theme.json has no effect, the control was never shown in the first place. This is most relevant for third-party blocks. Check the block’s block.json to see its declared supports.

A Complete Example: Editorial Blog Theme

Here is a complete settings section from a hypothetical editorial blog theme. This shows how to combine global settings with per-block overrides to create a coherent editing environment that enforces the design system while still giving editors meaningful choices:

This is a real, deployable configuration. Paragraphs and headings are locked down to prevent editors from introducing off-brand typography or colors. The pull quote block gets a restricted palette and size scale appropriate for its use as a callout element. Buttons can only use the theme palette. The result is an editor that guides content creators toward good decisions by design.

---

What Comes Next in This Series

This article is part of the Block Theme Fundamentals series. The previous articles covered the theme.json schema structure, global styles, and custom templates. In the next article we will look at how to define and register block patterns in your theme, creating reusable layout sections that editors can insert with one click. If you want a head start, how to create custom block patterns in WordPress block themes covers pattern registration in depth.

Understanding settings.blocks is foundational to building themes that work well in real production environments. The goal is never to build a theme for yourself, it is to build a theme that works for whoever is going to use the editor every day. Precise per-block configuration is how you make that happen.

---

Key Takeaways

• The settings.blocks section in theme.json lets you override global settings for individual blocks, giving fine-grained control over what editors see in the inspector
• Per-block settings always override global settings, use this to disable controls that would break your design on specific blocks
• appearanceTools: true is the fastest way to enable all appearance controls globally; then use settings.blocks to selectively disable what you do not want
• Color, typography, spacing, layout, and border controls can all be configured at the block level independently of global settings
• For client projects, locking down paragraph and heading blocks to prevent off-brand choices is almost always the right call
• Per-block settings work with third-party blocks that use useSettings from @wordpress/block-editor to read theme.json configuration

The official reference for all available per-block settings keys is the WordPress Block Editor Handbook, theme.json living reference. It is the authoritative source for what each setting does and which blocks support it.