Theme.json in Block Theme

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

Your email address will not be published. Required fields are marked *