Mountains Landscape Author Deni Eliash

Leveraging the theme.json File in WordPress to Add Custom CSS

  • ElPuas

  • 1/19/2023


When working with WordPress, the theme.json file can be a powerful tool for adding custom styles to your website. In this post, I'll explore how to use the CSS property in the theme.json file to add custom CSS to any WordPress website, as well as some best practices and tips to keep in mind.

Using the CSS property in theme.json:

One of the most useful properties in the theme.json file is the CSS property. This property allows you to add custom CSS styles to your website without the need for a separate CSS file. You can use the CSS property to define styles for specific elements, blocks, or even the entire website.

  "$schema": "",
  "version": 2,
  "settings": {
    "custom": {
      "w": {
        "full": "100vw",
        "half": "calc(var(--wp--style--global--content-size) / 2)"
      "img": {
        "grayscale": "contrast(1.1) grayscale(1)"
  "styles": {
    "color": {},
    "spacing": {},
    "typography": {},
    "elements": {},
    "blocks": {},
    "css": "body { background-color: var(--wp--preset--color--secondary); } .alignfull { margin: 0 calc(-50vw + 50%); width:var(--wp-custom-w-full); max-width:var(--wp-custom-w-full)} .wp-block-post-content, .wp-block-post-title { max-width: var(--wp--style--global--content-size); margin: 0 auto;} .has-drop-cap:not(:focus):first-letter { font-size: 7em; background: var(--wp--preset--color--primary); padding-top: 10px; padding-bottom: 4px;} .is-image-grayscale img { filter: var(--wp--custom--img--grayscale); } .has-grid-layout { display: grid; grid-template-columns: repeat(12,1fr); gap: 16px; height: 100%; } body .is-layout-flow.has-grid-layout > * { margin-top: 0; margin-block-start: 0;} .has-grid-layout > * { grid-column: span 6 / span 6; } .has-grid-layout > * > * { height: 100%; } body .is-layout-flow.has-grid-layout .wp-block-post-excerpt { margin-block-start: 0;} .has-grid-layout .wp-block-post-excerpt p { font-size: var(--wp--preset--font-size--size-14); } .jr-post-patterns section { height: 100%; } @media only screen and ( max-width: 600px ) { .has-grid-layout { grid-template-columns: 1fr; } .has-grid-layout > * { grid-column: span 1 / span 1; } } .has-grid-layout .wp-block-columns { margin-bottom: 0;}"

In this example, I use the CSS property to change the background color of the body, align elements using .alignfull class, change font-size of the first letter, and a filter effect of images using .has-drop-cap, .is-image-grayscale, and img.

Combining with custom property:

In addition to the CSS property, you can also use the custom property in the theme.json file to create custom CSS properties. These properties can be used to store reusable values, such as measurements or color codes, which can be referenced in your CSS.

/* Created by WordPress */

/* Used in theme.json CSS as: */
.alignfull { width:var(--wp--custom--w--full) };
.is-image-grayscale img { filter: var(--wp--custom--img--grayscale); }

In the example, I create two custom properties, w and img, which are used in the CSS to define width and filter effect of images.

Importing and parsing a CSS file?

As far as I know, it is not possible to import a CSS file directly into the theme.json and have it parsed as a string. However, an open question is if it is possible or not.


The theme.json file in WordPress provides a powerful way to add custom CSS to your website without the need for a separate CSS file. By using the CSS and custom properties, you can create custom styles and reusable values, which can help to make your CSS more modular and maintainable.

It's worth noting that while information on the CSS property in the theme.json file may be limited, it is a powerful tool that can be explored and used effectively. Based on my experience, it seems to be a viable option to add custom styles to your website, however, more information from WordPress community and official documentation would be helpful to understand its full capabilities, best practices, and limitations.

Keep in mind that although the theme.json file is a powerful tool, it's always a good idea to use it with caution and test your changes thoroughly before deploying them to a live website.

Update: Please note that in order to take advantage of the new Custom CSS functionality introduced in theme.json, the latest version of the Gutenberg plugin is required, Thanks to @dcook for the clarification.

© 2023 Built with Gatsby by El.Puas