Rajesh Rathod

Available for New Projects

Understanding theme.json Customization in WordPress

Written by

Rajesh Rathod

in

Question: theme.json Customization, what it is? What its capable of? How we can do that? Give a detailed examples along with codes.

The theme.json file is the backbone of WordPress block themes, acting as a central configuration file that defines your theme’s default styles, available options, and block behaviors. It’s incredibly powerful for customizing your site without plugins.

What is theme.json?

theme.json is a configuration file that:

  • Controls global styles, settings, and block-specific styles
  • Defines what customization options are available to users
  • Sets default values for spacing, colors, typography, and more
  • Creates a consistent styling system across your site

What Can theme.json Do?

With theme.json, you can:

  • Define custom color palettes
  • Set typography options (fonts, sizes, line heights)
  • Create custom spacing scales
  • Control block-specific defaults
  • Add custom CSS properties
  • Set layout constraints
  • Disable or enable specific features
  • Define custom gradients
  • Create responsive behavior
  • Set up duotone filters

How to Customize theme.json

  1. Access your theme files via FTP, SFTP, or your hosting file manager
  2. Navigate to your active theme’s directory
  3. Find the theme.json file (or create one if it doesn’t exist)
  4. Edit the file with any text editor
  5. Save and upload the changes

Comprehensive theme.json Example

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#0073aa",
          "name": "Primary"
        },
        {
          "slug": "secondary",
          "color": "#2c3338",
          "name": "Secondary"
        },
        {
          "slug": "accent",
          "color": "#ff6b6b",
          "name": "Accent"
        },
        {
          "slug": "background",
          "color": "#ffffff",
          "name": "Background"
        },
        {
          "slug": "text",
          "color": "#333333",
          "name": "Text"
        }
      ],
      "gradients": [
        {
          "slug": "primary-to-accent",
          "gradient": "linear-gradient(135deg, #0073aa 0%, #ff6b6b 100%)",
          "name": "Primary to Accent"
        }
      ],
      "duotone": [
        {
          "colors": ["#0073aa", "#ffffff"],
          "slug": "primary-white",
          "name": "Primary and White"
        }
      ],
      "custom": true,
      "customGradient": true,
      "link": true
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif",
          "slug": "system-font",
          "name": "System Font"
        },
        {
          "fontFamily": "Georgia, serif",
          "slug": "serif",
          "name": "Serif"
        }
      ],
      "fontSizes": [
        {
          "slug": "small",
          "size": "14px",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "18px",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "24px",
          "name": "Large"
        },
        {
          "slug": "x-large",
          "size": "32px",
          "name": "Extra Large"
        }
      ],
      "lineHeight": true,
      "fontWeight": true,
      "fontStyle": true,
      "textDecoration": true,
      "textTransform": true,
      "letterSpacing": true
    },
    "spacing": {
      "units": ["px", "em", "rem", "%", "vh", "vw"],
      "padding": true,
      "margin": true,
      "blockGap": true,
      "spacingSizes": [
        {
          "slug": "small",
          "size": "1rem",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "2rem",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "3rem",
          "name": "Large"
        }
      ]
    },
    "border": {
      "radius": true,
      "color": true,
      "style": true,
      "width": true
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    },
    "custom": {
      "spacing": {
        "baseline": "20px",
        "headerHeight": "80px",
        "footerHeight": "60px"
      },
      "typography": {
        "line-height": {
          "tiny": 1.15,
          "small": 1.4,
          "medium": 1.6,
          "large": 1.8
        }
      }
    }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--background)",
      "text": "var(--wp--preset--color--text)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system-font)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "spacing": {
      "blockGap": "2rem",
      "padding": {
        "top": "2rem",
        "right": "2rem",
        "bottom": "2rem",
        "left": "2rem"
      }
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--accent)"
          }
        }
      },
      "h1": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--x-large)",
          "fontWeight": "700",
          "lineHeight": "1.2"
        },
        "spacing": {
          "margin": {
            "top": "2rem",
            "bottom": "1rem"
          }
        }
      },
      "h2": {
        "typography": {
          "fontSize": "calc(var(--wp--preset--font-size--large) * 1.2)",
          "fontWeight": "700",
          "lineHeight": "1.3"
        }
      }
    },
    "blocks": {
      "core/paragraph": {
        "typography": {
          "lineHeight": "1.8"
        },
        "spacing": {
          "margin": {
            "bottom": "1.5rem"
          }
        }
      },
      "core/heading": {
        "color": {
          "text": "var(--wp--preset--color--secondary)"
        },
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--serif)"
        }
      },
      "core/button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "#ffffff"
        },
        "border": {
          "radius": "4px"
        },
        "typography": {
          "fontSize": "var(--wp--preset--font-size--medium)",
          "fontWeight": "600"
        },
        "spacing": {
          "padding": {
            "top": "0.75rem",
            "right": "1.5rem",
            "bottom": "0.75rem",
            "left": "1.5rem"
          }
        },
        ":hover": {
          "color": {
            "background": "var(--wp--preset--color--accent)"
          }
        }
      },
      "core/cover": {
        "spacing": {
          "padding": {
            "top": "3rem",
            "right": "3rem",
            "bottom": "3rem",
            "left": "3rem"
          }
        }
      },
      "core/image": {
        "border": {
          "radius": "8px"
        },
        "spacing": {
          "margin": {
            "bottom": "2rem"
          }
        }
      },
      "core/quote": {
        "typography": {
          "fontStyle": "italic",
          "fontSize": "var(--wp--preset--font-size--large)"
        },
        "border": {
          "width": "0 0 0 4px",
          "color": "var(--wp--preset--color--primary)",
          "style": "solid"
        },
        "spacing": {
          "padding": {
            "left": "2rem"
          },
          "margin": {
            "top": "2rem",
            "bottom": "2rem"
          }
        }
      }
    }
  },
  "templateParts": {
    "header": {
      "area": "header"
    },
    "footer": {
      "area": "footer"
    }
  }
}

Detailed Explanation of theme.json Sections

1. Settings

The settings section controls what options are available in the editor and their default values:

Color Settings

json"color": {
  "palette": [
    {
      "slug": "primary",
      "color": "#0073aa",
      "name": "Primary"
    }
  ]
}

This defines a color called “Primary” with the hex value #0073aa that can be used throughout the theme.

Typography Settings

json"typography": {
  "fontFamilies": [
    {
      "fontFamily": "Georgia, serif",
      "slug": "serif",
      "name": "Serif"
    }
  ],
  "fontSizes": [
    {
      "slug": "medium",
      "size": "18px",
      "name": "Medium"
    }
  ]
}

This defines available fonts and font sizes for the theme.

2. Styles

The styles section defines default styles for your theme:

Global Styles

json"styles": {
  "color": {
    "background": "var(--wp--preset--color--background)",
    "text": "var(--wp--preset--color--text)"
  },
  "typography": {
    "fontFamily": "var(--wp--preset--font-family--system-font)",
    "fontSize": "var(--wp--preset--font-size--medium)"
  }
}

Block-Specific Styles

json"blocks": {
  "core/paragraph": {
    "typography": {
      "lineHeight": "1.8"
    },
    "spacing": {
      "margin": {
        "bottom": "1.5rem"
      }
    }
  }
}

This sets specific styles just for paragraph blocks.

Real-World Examples

Example 1: Customizing Button Blocks

json"blocks": {
  "core/button": {
    "color": {
      "background": "var(--wp--preset--color--primary)",
      "text": "#ffffff"
    },
    "border": {
      "radius": "4px"
    },
    "typography": {
      "fontSize": "var(--wp--preset--font-size--medium)",
      "fontWeight": "600"
    },
    "spacing": {
      "padding": {
        "top": "0.75rem",
        "right": "1.5rem",
        "bottom": "0.75rem",
        "left": "1.5rem"
      }
    },
    ":hover": {
      "color": {
        "background": "var(--wp--preset--color--accent)"
      }
    }
  }
}

Example 2: Creating a Custom Quote Style

json"core/quote": {
  "typography": {
    "fontStyle": "italic",
    "fontSize": "var(--wp--preset--font-size--large)"
  },
  "border": {
    "width": "0 0 0 4px",
    "color": "var(--wp--preset--color--primary)",
    "style": "solid"
  },
  "spacing": {
    "padding": {
      "left": "2rem"
    },
    "margin": {
      "top": "2rem",
      "bottom": "2rem"
    }
  }
}

Tips for Working with theme.json

  1. Use Developer Tools: Inspect your site with browser developer tools to understand which elements you need to target.
  2. Start Small: Begin with simple modifications before attempting complex changes.
  3. Reference Variables: Use CSS variables (like var(--wp--preset--color--primary)) to maintain consistency.
  4. Backup First: Always make a backup of your theme.json file before editing.
  5. Test Changes: Check your modifications on different screen sizes and devices.
  6. Use WordPress Documentation: The official WordPress theme.json documentation is invaluable.

With these techniques, you can completely transform your WordPress block theme without using any plugins, giving you greater control and better performance.

Whats schema and version in this file?Edit

Understanding schema and version in theme.json

The $schema and version properties in a WordPress theme.json file serve important purposes for theme development and compatibility:

The $schema Property

The $schema property references the JSON Schema definition that validates your theme.json file:

json"$schema": "https://schemas.wp.org/trunk/theme.json"

What it does:

  1. Validation: It allows code editors to validate your theme.json structure against the official WordPress schema
  2. Autocompletion: Enables autocompletion in compatible editors (like VS Code)
  3. Documentation: Provides inline documentation and tooltips about available options
  4. Error Detection: Helps catch typos and incorrect property names

The URL points to the latest WordPress schema definition. You can also point to a specific version like:

  • https://schemas.wp.org/wp/6.1/theme.json
  • https://schemas.wp.org/wp/6.2/theme.json

The version Property

The version property indicates which version of the theme.json structure your file is using:

json"version": 2

What it means:

  • Version 1: The initial version introduced in WordPress 5.8
  • Version 2: Introduced in WordPress 5.9, with expanded features (current standard)

Why it matters:

  1. Feature Support: Different versions support different features
  2. Backward Compatibility: WordPress knows how to interpret your file based on this version
  3. Processing Logic: WordPress uses this to determine how to process your theme.json file

Version 2 is the current standard and includes support for:

  • More granular control over block-specific styles
  • Enhanced typography options
  • CSS variables and custom properties
  • Pseudo-selector styling (like :hover, :focus)
  • Template parts definitions
  • And many more features

Best Practices

  1. Always include both $schema and version in your theme.json file
  2. Use version 2 for modern WordPress themes
  3. Use the trunk schema for the latest features or a specific version schema if targeting older WordPress versions
  4. Keep these properties at the root level of your JSON structure

The combination of these properties ensures your theme.json file is properly validated and processed by WordPress.Retry

I want paragraph text color to be a gradient.Edit

Creating Gradient Text for Paragraphs in WordPress with theme.json

To create paragraph text with gradient colors using theme.json, you’ll need to use a combination of theme.json settings and some custom CSS properties. Here’s how to implement gradient text for paragraphs:

Method 1: Using theme.json with Custom CSS

Add this to your theme.json file:

theme.json with Gradient Text for Paragraphs

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "gradients": [
        {
          "slug": "text-gradient",
          "gradient": "linear-gradient(135deg, #ff6b6b 0%, #0073aa 100%)",
          "name": "Text Gradient"
        }
      ],
      "custom": true,
      "customGradient": true
    },
    "custom": {
      "gradient-text": {
        "property": "background",
        "value": "var(--wp--preset--gradient--text-gradient)"
      }
    }
  },
  "styles": {
    "blocks": {
      "core/paragraph": {
        "color": {
          "text": "transparent"
        },
        "css": "-webkit-background-clip: text; background-clip: text;"
      }
    }
  }
}

However, the above approach may not work in all themes because theme.json doesn’t directly support the CSS properties needed for gradient text. For better compatibility, you’ll need to add custom CSS.

Method 2: Adding Custom CSS in theme.json

theme.json with Custom CSS for Gradient Text

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "gradients": [
        {
          "slug": "text-gradient",
          "gradient": "linear-gradient(135deg, #ff6b6b 0%, #0073aa 100%)",
          "name": "Text Gradient"
        }
      ],
      "custom": true,
      "customGradient": true
    }
  },
  "styles": {
    "blocks": {
      "core/paragraph": {
        "typography": {
          "fontWeight": "bold"
        }
      }
    }
  },
  "customTemplates": [],
  "templateParts": []
}

Then, add this to your theme’s additional CSS (either through the Site Editor or in your style.css file):

Custom CSS for Gradient Text

.wp-block-paragraph {
  background: var(--wp--preset--gradient--text-gradient);
  -webkit-background-clip: text;
  background-clip: text;
  -webkit-text-fill-color: transparent;
  text-fill-color: transparent;
  display: inline-block;
}

Method 3: Using theme.json with Inline Styles

For more recent WordPress versions with better CSS support in theme.json:

Advanced theme.json for Gradient Text

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "gradients": [
        {
          "slug": "text-gradient",
          "gradient": "linear-gradient(135deg, #ff6b6b 0%, #0073aa 100%)",
          "name": "Text Gradient"
        }
      ]
    }
  },
  "styles": {
    "blocks": {
      "core/paragraph": {
        "css": "background: var(--wp--preset--gradient--text-gradient); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; text-fill-color: transparent; display: inline-block;"
      }
    }
  }
}

Important Notes:

  1. The display: inline-block property is important for proper gradient rendering
  2. Font weight affects how visible the gradient is – bolder text shows gradients better
  3. Support for gradient text varies slightly between browsers
  4. Test your implementation across different devices and browsers
  5. You might need to adjust the gradient values for optimal readability

If you want to add a class selector to only apply this to certain paragraphs, you can use the “Additional CSS Class” option in the block editor for specific paragraphs, then target those in your CSS instead of all paragraphs.

Would you like me to explain any specific part of this implementation in more detail?Retry

Claude can make mistakes. Please double-check responses.

More posts