WordPress block themes represent a fundamental shift in how themes are built. Instead of PHP template files that control every aspect of rendering, block themes use HTML templates with blocks, a central theme.json configuration file, and the Global Styles system. The result is themes that are more consistent, easier to customize, and compatible with the full block editor experience.
This guide covers how to build a block theme from scratch, from the essential files to advanced theme.json configuration to creating custom block patterns.
What Makes a Theme a Block Theme
A block theme is defined by its use of block templates rather than PHP template files. Instead of header.php, index.php, and footer.php, a block theme has a single index.html template composed entirely of blocks. The theme.json file handles all styling, replacing functions.php for most style-related configuration.
The minimum requirement for a block theme is a style.css file with the theme header, a theme.json file with basic settings, and an index.html template in the /templates directory. That’s it. Everything else is optional.
The theme.json File: Your Theme’s Control Center
theme.json replaces hundreds of lines of functions.php code. It controls color palettes, font sizes, typography settings, spacing presets, and block-specific styles. Everything is defined in a structured JSON format that’s consistent across all block themes.
The settings section defines what options are available to users in the editor — which colors they can choose, what font sizes are available, which blocks support which features. The styles section defines the actual CSS values that get applied. Separating settings from styles is one of the key innovations of theme.json.
Block Templates vs PHP Templates
Block templates are HTML files that use block markup instead of PHP. A template for a single post might include the Post Title block, the Post Content block, and the Comments block. Each block handles its own rendering and styling, eliminating the need for WordPress loop logic in your template files.
Template parts — header, footer, sidebar — are reusable HTML files stored in the /parts directory. They’re included in templates using the Template Part block. This creates a modular system where you can update your header in one place and it updates everywhere.
Global Styles and User Customization
One of the biggest advantages of block themes is the Global Styles system. Users can change colors, fonts, and spacing from the editor interface without writing CSS. The changes apply site-wide and persist through theme updates.
Define sensible defaults in your theme.json. Users can override them, but good defaults create a great first impression. Use the appearanceTools setting to enable common style options — padding, margin, border, and link color — without enabling every possible customization.
Block Patterns and Template Parts
Block patterns are pre-designed layouts that users can insert into any page or post. Register patterns in your theme by placing PHP files in the /patterns directory. WordPress automatically discovers and registers them.
Template parts are reusable components like headers, footers, and sidebars. Create them as HTML files in the /parts directory and assign them an area — header, footer, or general. Users can edit template parts from the Site Editor, making theme customization accessible to non-developers.
Adding Custom CSS
While block themes minimize the need for custom CSS, you’ll sometimes need it for specific design requirements. Add custom CSS using the styles.css property in theme.json for global overrides, or create a separate style.css file for CSS that can’t be expressed in theme.json.
Use CSS custom properties to maintain compatibility with Global Styles. WordPress generates CSS variables from theme.json settings that you can reference in your custom CSS.
The Bottom Line
Block themes are the future of WordPress theming. They’re simpler to build, more consistent to use, and more customizable for end users. If you haven’t built a block theme yet, start with a basic theme.json and a single template. As you get comfortable, add patterns, template parts, and custom block styles. The learning curve is worth it — block themes are faster to develop, easier to maintain, and provide a better experience for everyone.