Block theme setup

File structure

Block themes require a style.css file and a templates/index.html file. A block theme that supports WordPress 5.9 or older also requires an index.php file in the root folder.

You need to place all HTML template files inside the templates folder. If you place template files in the wrong folder, the theme will not load correctly.
Template part files are optional. If they are included, they must be placed inside a folder called parts.

The theme.json configuration file is optional but strongly recommended. Learn more about theme.json.

In addition to the required files, the theme can include a theme.json, a functions.php file, and any additional PHP files, CSS, images, or JavaScript to enhance the theme.

Example file structure:

patterns (dir)
      - example.php
parts (dir)
      - footer.html
      - header.html
      - 404.html
      - archive.html
      - index.html (required)
      - singular.html
style.css (required)

Top ↑

Theme setup function

An example setup function inside functions.php in a block theme may include wp-block-styles and an editor style:

if ( ! function_exists( 'myfirsttheme_setup' ) ) :
 * Sets up theme defaults and registers support for various WordPress features.
 * Note that this function is hooked into the after_setup_theme hook, which runs
 * before the init hook.
function myfirsttheme_setup() {
	// Add support for block styles.
	add_theme_support( 'wp-block-styles' );

	// Enqueue editor styles.
	add_editor_style( 'editor-style.css' );
endif; // myfirsttheme_setup
add_action( 'after_setup_theme', 'myfirsttheme_setup' );

This is significantly less code than what you may use to setup a classic theme.

Top ↑

Theme support

In block themes, the following theme supports are enabled automatically:

add_theme_support( 'post-thumbnails' );
add_theme_support( 'responsive-embeds' );
add_theme_support( 'editor-styles' );
add_theme_support( 'html5', array('style','script', ) );
add_theme_support( 'automatic-feed-links' );

Some theme supports are enabled when you include a setting in theme.json. The setting in theme.json takes precedence over add_theme_support().

Theme supportTheme.json setting
add_theme_support( ‘editor-font-sizes’, array() );settings.typography.fontSizes
add_theme_support( ‘custom-line-height’ );settings.typography.lineHeight
add_theme_support( ‘align-wide’ );settings.layout
add_theme_support( ‘editor-color-palette’, array() );settings.color.palette
add_theme_support( ‘editor-gradient-presets’, array() );settings.color.gradients
add_theme_support( ‘custom-spacing’ );settings.spacing
add_theme_support( ‘custom-units’, array() );settings.spacing.units

Top ↑

Including CSS for block styles

Please refer to the article, Including CSS & JavaScript.

Top ↑

Including JavaScript

Please refer to the article Loading JavaScript in the block editor handbook.


  • Created 2022-01-20