Summary: Learning about theme.json in WordPress block theme.
theme.json
is a configuration file introduced in WordPress 5.8 as part of the Full Site Editing (FSE) initiative. It allows theme developers to define global styles, settings, and behaviors for both the front-end and the block editor (Gutenberg) in a centralized and standardized manner. By leveraging theme.json
, developers can control the appearance and functionality of blocks, ensuring consistency and enhancing user experience.
- Centralized Configuration: Provides a single location to define theme-wide settings and styles.
- Declarative Styling: Enables defining styles in a structured JSON format rather than writing extensive CSS.
- Consistency: Ensures uniform styling across different blocks and components.
- Customization: Allows users to customize theme settings via the block editor interface.
- Performance: Can generate optimized CSS based on the defined settings, potentially reducing the amount of CSS loaded.
- Simplified Development: Reduces the need for writing repetitive CSS by leveraging JSON configurations.
- Enhanced User Control: Empowers users to adjust theme settings without touching code.
- Better Integration with FSE: Seamlessly integrates with Full Site Editing features, enhancing theme flexibility.
- Maintainability: Easier to manage and update theme styles through structured JSON rather than scattered CSS files.
- Scalability: Facilitates scaling themes with complex styling needs by providing a robust configuration system.
Structure of theme.json
At its core, theme.json
is a JSON file placed in the theme’s root directory. It defines various settings and styles that apply globally or to specific blocks. The basic structure includes:
{
"version": 2,
"settings": {},
"styles": {},
"customTemplates": {}
}
- version: Specifies the version of the
theme.json
schema being used. As of October 2023, version 2 is commonly used. - settings: Contains global and block-specific settings that define the behavior and options available in the block editor.
- styles: Defines global styles and styles for individual blocks.
- customTemplates: (Optional) Defines custom block templates and template parts for the theme.
Sections and Their Roles
Version
Specifies the schema version of theme.json
. Ensures compatibility with WordPress features and the block editor.
"version": 2
- Version 1: Initial implementation with basic settings and styles.
- Version 2: Enhanced features, more settings, and improved flexibility.
Settings
Defines global and block-specific settings that control the availability and behavior of various options in the block editor.
"settings": {
// Configuration here
}
Styles
Defines global styles and styles specific to individual blocks, allowing for comprehensive control over the visual presentation.
"styles": {
// Configuration here
}
Custom Templates
Allows defining custom block templates and template parts, facilitating Full Site Editing (FSE) capabilities.
"customTemplates": {
// Configuration here
}
Settings Configuration
The settings
section is pivotal in controlling what options are available to users in the block editor and defining global settings that affect blocks throughout the site.
Global Settings
Global settings apply to the entire site and all blocks unless overridden by block-specific settings.
"settings": {
"color": {},
"typography": {},
"spacing": {},
"layout": {},
// More settings...
}
Color Settings
Define color palettes, gradients, and other color-related options.
"settings": {
"color": {
"palette": [
{
"name": "Strong Magenta",
"slug": "strong-magenta",
"color": "#a156b4"
},
// More colors...
],
"gradients": [
{
"name": "Vivid Cyan Blue to Vivid Purple",
"slug": "vivid-cyan-blue-to-vivid-purple",
"gradient": "linear-gradient(135deg, #00c6ff 0%, #0072ff 100%)"
},
// More gradients...
],
"custom": true,
"customGradient": true
}
}
- palette: An array of color objects defining the color options available.
- gradients: An array of gradient objects for predefined gradient styles.
- custom: Boolean indicating if users can add custom colors.
- customGradient: Boolean indicating if users can add custom gradients.
Typography Settings
Control font sizes, font families, line heights, and other typography-related settings.
"settings": {
"typography": {
"fontSizes": [
{
"name": "Small",
"slug": "small",
"size": "12px"
},
// More font sizes...
],
"fontFamilies": [
{
"fontFamily": "Roboto, sans-serif",
"name": "Roboto",
"slug": "roboto"
},
// More font families...
],
"customFontSize": true,
"customFontFamily": true
}
}
- fontSizes: Defines the preset font sizes available.
- fontFamilies: Defines the available font families.
- customFontSize: Allows users to specify custom font sizes.
- customFontFamily: Allows users to specify custom font families.
Spacing Settings
Manage padding, margin, and other spacing-related settings.
"settings": {
"spacing": {
"customPadding": true,
"customMargin": true,
"units": [ "px", "em", "rem", "%" ],
"padding": {
"top": true,
"right": true,
"bottom": true,
"left": true
},
"margin": {
"top": true,
"right": true,
"bottom": true,
"left": true
}
}
}
- customPadding: Enables custom padding settings.
- customMargin: Enables custom margin settings.
- units: Specifies the units available for spacing.
- padding: Specifies which sides have padding controls.
- margin: Specifies which sides have margin controls.
Border Settings
Control border styles, widths, colors, and radii.
"settings": {
"border": {
"customColor": true,
"customRadius": true,
"customStyle": true,
"width": {
"top": true,
"right": true,
"bottom": true,
"left": true
},
"radius": {
"topLeft": true,
"topRight": true,
"bottomLeft": true,
"bottomRight": true
}
}
}
- customColor: Allows custom border colors.
- customRadius: Allows custom border radii.
- customStyle: Allows custom border styles (e.g., solid, dashed).
- width: Controls for border widths on each side.
- radius: Controls for border radii on each corner.
Layout Settings
Define layout-related settings such as content width, wide and full-width alignment.
"settings": {
"layout": {
"contentSize": "800px",
"wideSize": "1200px",
"flexibleWidth": true,
"inherit": false
}
}
- contentSize: Defines the default content width.
- wideSize: Defines the maximum width for wide-aligned content.
- flexibleWidth: Allows the content width to be flexible/responsive.
- inherit: Determines if layout settings can be inherited by child blocks.
Custom Properties
Allows defining custom CSS variables that can be used throughout the theme.
"settings": {
"custom": {
"myCustomProperty": "value"
}
}
- Define reusable variables for colors, sizes, etc.
- Facilitate dynamic theming and easier maintenance.
Styles Configuration
The styles
section defines the visual appearance of blocks and global elements. It allows setting default styles that apply across the site or to specific blocks.
Global Styles
Set styles that apply universally unless overridden by block-specific styles.
"styles": {
"color": {
"background": "#ffffff",
"text": "#000000"
},
"typography": {
"fontSize": "16px",
"fontFamily": "Roboto, sans-serif",
"lineHeight": "1.5"
},
"spacing": {
"padding": {
"top": "20px",
"right": "20px",
"bottom": "20px",
"left": "20px"
}
}
}
- color: Global background and text colors.
- typography: Global font size, family, and line height.
- spacing: Global padding and margins.
Block-Specific Styles
Override or define styles for specific blocks.
"styles": {
"blocks": {
"core/paragraph": {
"typography": {
"fontSize": "18px"
},
"color": {
"text": "#333333"
}
},
"core/button": {
"color": {
"background": "#0073aa",
"text": "#ffffff"
},
"border": {
"radius": "4px"
}
}
}
}
- core/paragraph: Sets a larger font size and darker text color for paragraph blocks.
- core/button: Defines specific background and text colors, and rounded corners for button blocks.
Responsive Styles
Define styles that adjust based on screen size or other responsive criteria.
"styles": {
"blocks": {
"core/columns": {
"spacing": {
"margin": {
"top": {
"desktop": "40px",
"tablet": "30px",
"mobile": "20px"
}
}
}
}
}
}
- Use nested objects to define styles for different breakpoints (desktop, tablet, mobile).
- Ensure responsive design by adapting styles based on device or screen size.
Custom Templates
The customTemplates
section allows defining pre-configured block structures, facilitating consistent layouts and speeding up content creation.
Template Parts
Define reusable parts of the site, such as headers, footers, and sidebars.
"customTemplates": {
"templateParts": {
"header": {
"title": "Header",
"content": "<!-- wp:group --><div class=\"wp-block-group\"><!-- wp:site-title /--></div><!-- /wp:group -->"
},
"footer": {
"title": "Footer",
"content": "<!-- wp:group --><div class=\"wp-block-group\"><!-- wp:paragraph --><p>© 2024 My Site</p><!-- /wp:paragraph --></div><!-- /wp:group -->"
}
}
}
- header: Defines a header template part with a site title.
- footer: Defines a footer template part with a copyright.
Full Site Editing (FSE) Templates
Define complete site layouts using blocks, enhancing the flexibility of site design.
"customTemplates": {
"templates": {
"home": {
"title": "Home",
"content": "<!-- wp:group --><div class=\"wp-block-group\"><!-- wp:paragraph --><p>Welcome to our website!</p><!-- /wp:paragraph --></div><!-- /wp:group -->"
},
"single-post": {
"title": "Single Post",
"content": "<!-- wp:post-title /--><!-- wp:post-content /-->"
}
}
}
- home: A simple home page with a welcome message.
- single-post: A single post template displaying the post title and content.
Custom Properties and Variables
Define custom CSS variables to create dynamic and reusable styles.
"settings": {
"custom": {
"myTheme": {
"primaryColor": "#0073aa",
"secondaryColor": "#005177"
}
}
},
"styles": {
"elements": {
"link": {
"color": {
"text": "var(--wp--custom--myTheme--primaryColor)"
}
}
}
}
- Reusability: Define once, use multiple times across styles.
- Dynamic Theming: Easily update theme colors or other properties by changing the variable value.
- Maintainability: Simplifies updates and reduces the risk of inconsistencies.
Conditional Styles and Settings
Apply styles or settings based on certain conditions, such as screen size or user preferences.
"styles": {
"blocks": {
"core/image": {
"border": {
"radius": {
"mobile": "0px",
"desktop": "10px"
}
}
}
}
}
- Responsive Design: Adjust styles for different devices.
- User Preferences: Adapt styles based on user-selected themes (light/dark mode).
Basic theme.json
A simple theme.json
defining global colors, font sizes, and basic styles.
{
"version": 2,
"settings": {
"color": {
"palette": [
{ "name": "Black", "slug": "black", "color": "#000000" },
{ "name": "White", "slug": "white", "color": "#ffffff" }
],
"custom": false
},
"typography": {
"fontSizes": [
{ "name": "Small", "slug": "small", "size": "12px" },
{ "name": "Normal", "slug": "normal", "size": "16px" },
{ "name": "Large", "slug": "large", "size": "24px" }
],
"customFontSize": false
}
},
"styles": {
"color": {
"background": "#ffffff",
"text": "#000000"
},
"typography": {
"fontSize": "16px",
"fontFamily": "Arial, sans-serif"
}
}
}
Leave a Reply