Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Create a Block Theme From Scratch

How to Create a Block Theme From Scratch

Short answer

To create a block theme from scratch, make a theme folder with templates/index.html, style.css, and theme.json, then zip it and upload it under Appearance, then Themes, then Add New. Set colors, fonts, and widths in theme.json, build one HTML template per view, and add header and footer parts in the parts folder.

Key takeaways

  • A block theme needs only templates/index.html, style.css, and theme.json.
  • Block themes arrived in WordPress 5.9, and their styling lives in theme.json.
  • theme.json version 3 is the latest format, introduced in WordPress 6.6.
  • The Create Block Theme plugin can build a blank theme from the dashboard.
  • theme.json overrides default styles, and user values override both.
  • Upload a block theme as a zip under Appearance, then Themes, then Add New.

What is a block theme?

A block theme is a WordPress theme built mainly from block markup and a theme.json file, so you can edit the whole site in the Site Editor.

A block theme uses blocks as its main building material. Templates, template parts, and styles are all blocks or settings, not PHP files. The Site Editor can then show and change the header, the footer, the templates, and the styles in one place.

The idea landed in WordPress 5.9. The WordPress Developer Blog states that since the concept landed in WordPress 5.9, almost none of the styling of these themes happens in CSS files, and that block themes use the machine-readable theme.json format instead. The Style Book states that (checked November 2026).

A classic theme uses PHP template files and the Customizer. A block theme uses HTML block templates and the Site Editor. A guide on block themes vs classic themes explains the split in more depth.

Block themes are now common. WordPress.org lists 1,985 block themes in its theme directory tag page. Block themes shows that count (checked November 2026).

What do you need before you start?

You need a local WordPress install, a code editor, and a plan for the templates and styles before you write any files.

Set up a local site first, so a mistake cannot break a live site. The Theme Handbook notes that its first-theme steps assume you have already finished the section on setting up a development environment. Your First Theme states that (checked November 2026).

Pick a folder name for the theme, such as my-first-theme, and keep it lowercase with dashes. The folder name becomes the theme slug, and it should be short and plain.

Sketch the design before you write files. List the templates you need, such as the home page, a single post, a page, and an archive, plus the header and footer parts. Then list the colors, fonts, and widths in theme.json so the whole site shares them.

Allow 2 to 4 hours for a first small block theme, including the install and the checks below. The files are few, and most of the time goes to the templates and the styles.

What files does a block theme need?

A block theme needs only three files: templates/index.html, style.css, and theme.json.

The Theme Handbook states that the only files needed for a block theme are three: index.html in a templates folder, style.css, and theme.json.

The handbook states that index.html is the main template to display your list of posts, style.css styles the content, and theme.json sets style properties in a structured way. Your First Theme gives that list (checked November 2026).

As the theme grows, add more templates and template parts. The handbook lists archive.html, single.html, and page.html as template examples, and header.html, footer.html, and sidebar.html as template part examples. Your First Theme lists those files (checked November 2026).

FileWhere it goesWhat it does
style.cssTheme rootHolds the theme header and extra CSS
theme.jsonTheme rootHolds settings, styles, and presets
templates/index.htmltemplates/ folderMain template for the post list
templates/single.htmltemplates/ folderTemplate for one post
templates/page.htmltemplates/ folderTemplate for one page
templates/archive.htmltemplates/ folderTemplate for archives
parts/header.htmlparts/ folderHeader template part
parts/footer.htmlparts/ folderFooter template part

The structure of a finished starter theme looks like this:

templates/
index.html
style.css
theme.json

That shape comes from the handbook, which shows the same four lines after the first three files are made. Your First Theme shows that structure (checked November 2026).

How do you write style.css and theme.json?

Write style.css with the theme header comment, and theme.json with version, settings, and styles for the site.

Start with style.css. The handbook gives this header as the whole file for a first theme:

/*
Theme Name: My First WordPress Theme
*/

That comment tells WordPress the theme name. Add more lines later, such as Description, Author, and Version, but the name line is the one WordPress needs to list the theme.

Next, create theme.json in the theme root folder. The handbook gives this starter content, with version 2 and layout widths of 840 pixels for content and 1,100 pixels for wide blocks:

{
    "version": 2,
    "settings": {
        "layout": {
            "contentSize": "840px",
            "wideSize": "1100px"
        }
    }
}

The theme.json file arrived in WordPress 5.8 as a new way to configure the editor.

The Block Editor Handbook states that WordPress 5.8 comes with a new mechanism to configure the editor, the theme.json file, and that the file should sit inside the root of the theme directory. Global Settings and Styles (theme.json) states that (checked November 2026).

The latest version of the format is version 3, introduced in WordPress 6.6.

The handbook states that new versions are introduced when a breaking change needs to be made, and that older versions of theme.json are backwards-compatible and will keep working with newer versions of WordPress. Global Settings and Styles (theme.json) states that (checked November 2026).

Use the settings section for presets such as colors, font sizes, and gradients, and the styles section for the values that apply them.

A preset color becomes a CSS custom property such as --wp--preset--color--black for a black preset. Global Settings and Styles (theme.json) gives that naming rule (checked November 2026).

The style engine then builds the CSS from those settings. The Developer Blog states that the style engine API consolidates style definitions from core, themes, and users, and generates the theme CSS classes and custom properties. The Style Book states that (checked November 2026).

A guide on how to use theme.json covers the settings and styles sections in more depth.

How do you build the templates?

Build one HTML template per view, starting with index.html, and fill each one with block markup.

Create a templates folder inside the theme folder, then create index.html inside it. The handbook states that index.html is the main template to display your list of posts. Your First Theme states that (checked November 2026).

A post list template holds a Query Loop block, which lists the posts, with a Post Title block and a Post Content block inside it for each post. A single post template holds the same blocks without the loop, since it shows one post.

Name each template after the view it serves. single.html serves one post, page.html serves one page, archive.html serves a list such as a category page, and 404.html serves the not-found page.

Keep each template short. A template should name the parts and the blocks in order, and leave the look to theme.json and the Site Editor. Long templates are hard to read and hard to change later.

Check the template names against the handbook list as you add files. The handbook lists index.html, archive.html, single.html, and page.html as the template examples to start from. Your First Theme lists them (checked November 2026).

How do you add template parts and patterns?

Add header and footer template parts in the parts folder, and reusable block patterns for repeated layouts.

Template parts are small templates that more than one page shares. A header part holds the site title, the logo, and the navigation, and a footer part holds the footer text and links. Each template then points to those parts instead of repeating them.

The handbook lists header.html, footer.html, and sidebar.html as template part examples, and states that you can create a parts directory inside the theme folder and put template parts there. Your First Theme states that (checked November 2026).

A guide on how to edit the header in a block theme shows how the header part is changed in the Site Editor once the theme is active.

Block patterns are ready-made groups of blocks for a repeated layout, such as a hero section or a callout. A guide on how to use block patterns in WordPress explains how to add and reuse them.

Keep the parts folder small. One header, one footer, and one sidebar cover most small themes, and each extra part adds a file to keep in sync.

How do you use the Create Block Theme plugin instead?

The Create Block Theme plugin can build the same blank theme from the dashboard, with no files to write by hand.

The plugin works with the Site Editor to let you create and edit block themes from the WordPress dashboard.

Learn WordPress states that whether you are building a new theme on top of a base theme or starting a brand new block theme from scratch, you will find Create Block Theme useful. Streamline your Block Theme development with Create Block Theme states that (checked November 2026).

Install it from Plugins, then Add New, and search for “Create Block Theme”. Once it is active, the Create Block Theme submenu appears under the Appearance menu in the dashboard. Streamline your Block Theme development with Create Block Theme gives those steps (checked November 2026).

The blank theme option asks for the theme name, description, theme URI, author, and author URI.

Learn WordPress states that only the theme name is required to create a blank theme, since it is needed to create the theme directory. Streamline your Block Theme development with Create Block Theme states that (checked November 2026).

The plugin creates the required style.css and an index.html template, plus a theme.json file to manage global styles, a readme.txt file, and header and footer template parts. Streamline your Block Theme development with Create Block Theme lists those files (checked November 2026).

The plugin gives five ways to work with a theme. Make WordPress Themes lists them as Export, Create a child theme, Clone the current theme, Overwrite theme files, and Create blank theme. Create Block Theme lists those five (checked November 2026).

The Overwrite option writes changes saved in the database back to the theme files, which is handy when you want to keep the changes in version control.

The Export option writes the active theme and its saved changes to an installable zip file. Streamline your Block Theme development with Create Block Theme states both uses (checked November 2026).

How do you install, activate, and check the theme?

Zip the theme folder, upload it under Appearance, then Themes, then Add New, and activate it to check it.

The handbook gives the install steps: make a ZIP file of the theme directory, go to the WordPress admin panel, then Appearance, then Themes, then Add New, then Upload, upload the zip, click Install, and then Activate. Your First Theme gives those steps (checked November 2026).

After activation, open the Site Editor from Appearance, then Editor, and walk through the templates.

The Style Book lives there too: it is one place where you can set all the styles for a site, and it arrived in the Global Styles interface in WordPress 6.2. The Style Book states that (checked November 2026).

Check the home page, one post, one page, and one archive on a phone screen as well as a desktop screen. The content width of 840 pixels and the wide width of 1,100 pixels from the starter theme.json should hold on both.

Remember the style order when a value looks wrong. The Developer Blog states that theme.json overrides the default WordPress styles, and that user values, the ones set in the settings fields, override both. The Style Book states that order (checked November 2026).

What mistakes should you avoid?

Avoid editing the live theme files by hand, mixing PHP templates into a block theme, and skipping the check on a phone screen.

Do not edit the theme on the live site. Build it on a local install, zip it, and upload it, so a broken file cannot take the live site down.

Do not add PHP template files to a block theme. The theme is read from block markup and theme.json, and PHP templates do not belong in that shape. If you need PHP logic, put it in a small plugin instead.

Do not set colors and font sizes in style.css when theme.json can hold them. Values in theme.json show up in the Site Editor, while values buried in CSS do not.

Do not skip the Style Book check. Open it from the Styles panel in the Site Editor and look at every block type, since a color or font size that looks fine on a paragraph can look wrong on a quote or a button.

Frequently asked questions

What is the smallest set of files for a block theme?

Yes. A block theme needs only three files: templates/index.html, style.css, and theme.json. Add more templates, such as single.html and page.html, plus header and footer parts, as the theme grows. The Theme Handbook lists those three as the only files needed.

Can I create a block theme without writing files by hand?

Yes. Install the Create Block Theme plugin, open it under Appearance, and pick Create blank theme. Only the theme name is required. The plugin creates style.css, index.html, theme.json, a readme.txt file, and header and footer parts for you.

What is the difference between a block theme and a classic theme?

No. Block themes use HTML block templates and theme.json, while classic themes use PHP template files and the Customizer. A block theme lets you edit the header, footer, templates, and styles in the Site Editor.

Where do I set the colors and fonts for a block theme?

Put the color, font size, and layout settings in theme.json, under settings and styles. Values set there show up in the Site Editor, and the style engine turns presets into CSS custom properties such as --wp--preset--color--black.

How do I save Site Editor changes back to the theme files?

Use the Overwrite option in the Create Block Theme plugin, which writes changes saved in the database back to the theme files. That keeps the files in step with the editor, so you can keep them in version control.

How do I install a block theme I built on my computer?

Zip the theme folder, upload it under Appearance, then Themes, then Add New, then Upload, and activate it. Then open the Site Editor and check the home page, one post, one page, and one archive on a phone screen and a desktop screen.

Sources

  1. Your First Theme WordPress Developer Resources
  2. Global Settings & Styles (theme.json) WordPress Developer Resources
  3. Streamline your Block Theme development with Create Block Theme Learn WordPress
  4. The Style Book: a one-stop shop for styling block themes WordPress Developer Resources
  5. Create Block Theme Make WordPress Themes
  6. Block themes WordPress.org

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test