Theme.json Configuration

The theme.json file is a powerful configuration tool that controls the WordPress Block Editor’s behavior, appearance, and available features. You can use it to define global settings, customize block supports, and create a cohesive design system for your theme.

What is theme.json?

Theme.json is a JSON configuration file that allows you to:

Control which editor features are available to users
Define global design tokens (colors, typography, spacing)
Configure block-level settings and styles
Create a consistent design system across your site

Schema Structure

The theme.json file follows a versioned schema. Here’s the basic structure:

{
  "version": 3,
  "settings": {
    // Global settings
  },
  "styles": {
    // Global styles
  }
}

Always use "version": 3 for the latest schema. This ensures you have access to all current features.

Settings Configuration

Color Settings

You can define a custom color palette and control color-related features:

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "Primary"
        },
        {
          "slug": "secondary",
          "color": "#ff5837",
          "name": "Secondary"
        }
      ],
      "custom": true,
      "customDuotone": true,
      "customGradient": true,
      "defaultPalette": false
    }
  }
}

{
  "version": 3,
  "settings": {
    "color": {
      "background": false,
      "text": false,
      "custom": false,
      "customDuotone": false,
      "customGradient": false,
      "defaultPalette": false
    }
  }
}

Typography Settings

Define font families, sizes, and typography controls:

{
  "version": 3,
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto",
          "slug": "system",
          "name": "System Font"
        }
      ],
      "fontSizes": [
        {
          "slug": "small",
          "size": "0.875rem",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "1rem",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "1.5rem",
          "name": "Large"
        }
      ],
      "customFontSize": true,
      "lineHeight": true,
      "letterSpacing": true
    }
  }
}

Layout Settings

Control the default content width and layout options:

{
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "750px",
      "wideSize": "1200px"
    }
  }
}

To disable the “Inherit default layout” setting for container blocks like the Group block, remove or set contentSize and wideSize to null.

Block-Level Settings

You can configure settings for specific blocks using the blocks key:

Customize Specific Block
Restrict Block Features

{
  "version": 3,
  "settings": {
    "color": {
      "customDuotone": false
    },
    "blocks": {
      "core/post-featured-image": {
        "color": {
          "duotone": [
            {
              "colors": ["#282828", "#ff5837"],
              "slug": "black-and-orange",
              "name": "Black and Orange"
            }
          ],
          "customDuotone": true,
          "custom": true
        }
      }
    }
  }
}

{
  "version": 3,
  "settings": {
    "blocks": {
      "core/heading": {
        "color": {
          "background": false,
          "text": true
        },
        "typography": {
          "fontSizes": [
            {
              "slug": "heading-small",
              "size": "1.5rem",
              "name": "Small"
            },
            {
              "slug": "heading-large",
              "size": "3rem",
              "name": "Large"
            }
          ]
        }
      }
    }
  }
}

Limiting Editor Features

You can create a highly restricted editing experience by disabling most features:

{
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "750px"
    },
    "color": {
      "background": false,
      "custom": false,
      "customDuotone": false,
      "customGradient": false,
      "defaultGradients": false,
      "defaultPalette": false,
      "text": false
    },
    "typography": {
      "customFontSize": false,
      "dropCap": false,
      "fontStyle": false,
      "fontWeight": false,
      "letterSpacing": false,
      "lineHeight": false,
      "textDecoration": false,
      "textTransform": false
    }
  }
}

Styles Configuration

Define global and block-specific styles:

{
  "version": 3,
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#000000"
    },
    "typography": {
      "fontSize": "1rem",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": {
        "color": {
          "text": "#007cba"
        },
        ":hover": {
          "color": {
            "text": "#005a87"
          }
        }
      },
      "h1": {
        "typography": {
          "fontSize": "2.5rem",
          "lineHeight": "1.2"
        }
      }
    },
    "blocks": {
      "core/button": {
        "color": {
          "background": "#007cba",
          "text": "#ffffff"
        },
        "border": {
          "radius": "4px"
        }
      }
    }
  }
}

CSS Custom Properties

Theme.json automatically generates CSS custom properties from your presets:

{
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#007cba",
          "name": "Primary"
        }
      ]
    }
  }
}

This generates the following CSS:

:root {
  --wp--preset--color--primary: #007cba;
}

.has-primary-color {
  color: var(--wp--preset--color--primary);
}

.has-primary-background-color {
  background-color: var(--wp--preset--color--primary);
}

Common Use Cases

Curating the Editor Experience

Restrict editor features while maintaining design consistency:

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {"slug": "primary", "color": "#007cba", "name": "Primary"},
        {"slug": "secondary", "color": "#ff5837", "name": "Secondary"}
      ],
      "custom": false,
      "defaultPalette": false
    },
    "blocks": {
      "core/paragraph": {
        "color": {
          "background": false
        }
      }
    }
  }
}

Duotone Configuration

Provide predefined duotone filters:

{
  "version": 3,
  "settings": {
    "color": {
      "duotone": [
        {
          "colors": ["#000000", "#ffffff"],
          "slug": "foreground-and-background",
          "name": "Foreground and background"
        },
        {
          "colors": ["#000000", "#7f5dee"],
          "slug": "foreground-and-tertiary",
          "name": "Foreground and tertiary"
        }
      ],
      "customDuotone": true
    }
  }
}

Best Practices

Start with a minimal configuration: Only define what you need to override
Use meaningful slug names: Make them descriptive for better developer experience
Test across blocks: Verify your settings work as expected across different block types
Document your choices: Add comments (in your theme documentation) explaining why certain features are disabled
Consider accessibility: Ensure your color combinations meet WCAG contrast requirements

Next Steps

Learn about Server-side theme.json Filters
Explore Editor Customization techniques
Read the theme.json reference documentation

Overview

Getting Started

Core Concepts

Block Development

Advanced Guides

What is theme.json?

Schema Structure

Settings Configuration

Color Settings

Typography Settings

Layout Settings

Block-Level Settings

Limiting Editor Features

Styles Configuration

CSS Custom Properties

Common Use Cases

Curating the Editor Experience

Duotone Configuration

Best Practices

Next Steps

​What is theme.json?

​Schema Structure

​Settings Configuration

​Color Settings

​Typography Settings

​Layout Settings

​Block-Level Settings

​Limiting Editor Features

​Styles Configuration

​CSS Custom Properties

​Common Use Cases

​Curating the Editor Experience

​Duotone Configuration

​Best Practices

​Next Steps

What is theme.json?

Schema Structure

Settings Configuration

Color Settings

Typography Settings

Layout Settings

Block-Level Settings

Limiting Editor Features

Styles Configuration

CSS Custom Properties

Common Use Cases

Curating the Editor Experience

Duotone Configuration

Best Practices

Next Steps