WordPress Block Theme Development Step by Step

Key points:

• Block themes enable full visual control of design and layout using the WordPress block editor.
• Development involves setting up locally, creating core files and templates, customizing, and then deploying.
• Advanced Custom Fields (ACF®) simplifies custom block creation with PHP, avoiding complex JavaScript or React.

Building a WordPress block theme is a straightforward way to create a more flexible and customizable site.

Unlike classic themes, block themes give you control over both design and layout, all through the WordPress block editor. The real appeal is the ability to customize content on the fly without touching a line of code, which feels like a natural step forward for anyone used to the traditional WordPress experience.

For even smoother sailing, you can use Advanced Custom Fields (ACF®). ACF Blocks (a feature of PRO) lets you easily build custom blocks that fit right into your theme for more tailored designs.

If you’re used to classic themes, you might be hesitant to try this new approach. Once you get the hang of it, though, you’ll see how much more intuitive and efficient block-based design can be. Let’s take a look.

Understanding the WordPress block theme structure

The structure of a WordPress block theme revolves around several key components that work together to create a flexible and customizable design:

• The theme.json file defines global design settings for a block theme, such as typography, color schemes, and block-specific styles. It improves block themes by being a central configuration file that streamlines design management across the site.
• Templates in block themes use HTML files like index.html, single.html, and page.html to structure page layouts. These templates allow content to be arranged with blocks, offering flexibility without relying on PHP.
• Block templates define how collections of blocks appear on the site. They enable customization of content display, allowing you to design layouts tailored to specific content types.
• The style.css file provides theme metadata and can include custom styles that aren’t managed by theme.json. It ensures compatibility with older versions of WordPress and allows for additional design adjustments.
• The functions.php file remains in block themes for custom functions or features that aren’t handled by the block editor. While its role has diminished, it’s still useful for adding specific functionality or tweaks.

Build your first block theme step-by-step

Now that you understand what goes into a block theme, it’s time to build one. Here’s a teaser for just how simple the folder structure is:

1. Set up a local WordPress development environment

You’ll need to spin up WordPress on your device so you can build and test things without touching a live site. There are many tools you can use to accomplish this, but the best one is LocalWP.

LocalWP is 100% free, but it provides features you’d expect from a paid tool, including one-click cloud backups, hot-swapping between web servers and PHP versions, and powerful developer tools like shell access and WP-CLI. Its setup is painless, and you should be up and running in a few minutes.

For code editing, we recommend using an Integrated Development Environment (IDE) rather than a basic text editor. Visual Studio Code is also free, and it accelerates development with features such as syntax highlighting, linting, and file search.

2. Create the theme folder and core files

Now you’ll add the basic files WordPress needs to recognize your theme:

1. In wp-content/themes/, create a new folder, e.g., my-block-theme.
2. Inside it, create your style.css, and add the following theme details to the top of the file:

/*
Theme Name: My Block Theme
Version: 1.0
*/

3. Create a theme.json file and add the following structure:

{
  "version": 2,
  "settings": {},
  "styles": {},
  "customTemplates": [],
  "templateParts": []
}

4. Go to Appearance > Themes in your WordPress admin to activate the theme.

5. Confirm that no errors appear and the theme loads with a basic structure.

3. Create template and template part folders

With the theme activated, set up folders that define your site’s layout and reusable sections.

Inside your theme folder, create two new folders: templates and parts. These will hold .html files used by the Site Editor.

Files in templates/ define full-page layouts (e.g., index.html, page.html), while files in parts/ define reusable blocks like headers and footers (e.g., header.html, footer.html).

Keep the structure flat – WordPress scans both folders automatically.

Don’t include PHP files; block themes are rendered entirely in HTML and block markup.

4. Build theme templates

Now you’ll define how different parts of the site are rendered using blocks and block templates.

1. Create a file named index.html inside the templates/ folder and add basic layout markup:

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:post-title /-->
<!-- wp:post-content /-->
<!-- wp:template-part {"slug":"footer"} /-->

2. In parts/, create header.html with markup like:

<!-- wp:group -->
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
<!-- /wp:group -->

3. Create footer.html in the same way (e.g., a group with site info or footer menu).
4. Add more templates in templates/, like single.html, page.html, and 404.html, depending on your site’s needs.

Use the Site Editor to visually design and export templates if you prefer not to write them manually.

For a more modular approach, consider creating custom blocks using ACF Blocks, which come as part of ACF PRO. They integrate directly with block themes and offer full control over markup and fields. This includes the ability to display custom field values without any complex state management or REST endpoints.

ACF Blocks improves block themes by letting you ship React-rendered Gutenberg blocks with the familiar PHP templating you already know, collapsing days of JavaScript-heavy work into a single morning’s sprint.

5. Use the Site Editor to test and fine-tune

With your templates in place, use the Site Editor to preview, edit, and adjust layouts visually.

In the WP admin dashboard, go to Appearance > Editor, then open a template and preview how it renders with real content.

Use the block inspector to change spacing, alignment, font sizes, and other style settings. Use the Global Styles panel to edit site-wide settings, such as fonts, colors, and layout.

Save your changes when you’re done – WordPress writes them to the corresponding .html files if you want to review them. If changes don’t apply, check theme.json or re-save templates in the editor.

6. Deploy the theme

Once your theme is ready, you can install it on live sites or distribute it to others:

1. Go to your theme folder and compress it into a .zip file.
2. Log in to the WordPress admin of your target site.
3. Go to Appearance > Themes > Add New > Upload Theme.
4. Upload the .zip, install, and activate it.

5. Test all pages, templates, and custom blocks in the live environment to ensure they function as expected.

To distribute the theme for free, submit it to the WordPress Theme Directory. For commercial themes, use marketplaces like ThemeForest or sell it directly via your own site.

However you choose to distribute the theme, you should always include a screenshot.png, readme.txt, and license info in your theme folder. Version your theme using Git, bump the version number in style.css before each release, and document any required plugins or settings.

Best practices for building WordPress block themes

If everything went according to plan earlier, you’ve got a working block theme, but here’s how to get rid of any lingering jank:

• Structure your theme with a clear block-based architecture to separate template parts, block styles, and block variations for better site scalability. Well-named directories, such as template-parts, blocks, and assets, ensure a logical separation of concerns and ease future development.
• Extend blocks using custom variations in theme.json to provide a consistent design system while enabling content creators to use pre-defined styles without manually applying CSS classes.
• Avoid overloading functions.php by moving any complex logic into separate files or custom plugins instead.
• Minimize inline styles and scripts by relying on external stylesheets and scripts wherever possible. This ensures that the browser can cache assets effectively, improving performance, and keeps your markup maintainable.
• Use the Block Editor’s built-in hooks, like enqueue_block_assets, enqueue_block_editor_assets, and block_type_metadata, to inject styles and scripts only when necessary. This ensures better performance by limiting resource loading to relevant areas of the editor or frontend.
• Optimize block rendering for performance by minimizing unnecessary HTML output and ensuring that expensive queries or operations are executed conditionally or deferred. Additionally, cache the render_callback output for dynamic blocks to avoid repeated, costly operations on each page load.

Build smarter WordPress block themes with ACF Blocks

WordPress block themes offer a flexible, modern approach to theme development by relying on the block-based system introduced with the block editor.

These themes are structured around the theme.json file for settings and styles, as well as various template files for layout control. Block templates and template parts allow for more modularity, while dynamic blocks offer rich functionality.

However, building and managing custom blocks can be complex and time-consuming. Unless, of course, you’re using ACF Blocks.

ACF Blocks makes it much easier to create custom blocks without needing to dive deep into JavaScript or React. For agencies, that speed and polish arguably recoup the entire cost of ACF PRO on the very first client project, while giving editors an intuitive interface that keeps them begging for more.

Unlock a streamlined but versatile approach to WordPress block theme development with ACF Blocks and everything else in ACF PRO today.