Block theme setup

File structure

Two files are required to activate any theme: index.php and style.css. Block themes must also include a index.html template inside a folder called templates. -If template files are placed in the wrong folder, the theme will not load correctly. Template parts 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, any additional PHP files, CSS, images, or JavaScript to enhance the theme.

Example file structure:

assets (dir)
      - css (dir)
            - blocks (dir)
      - images (dir)
      - js (dir)
inc (dir)
patterns (dir)
parts (dir)
      - footer.html
      - header.html
templates(dir)
      - 404.html
      - archive.html
      - index.html
      - page.html
      - single.html
      - search.html
functions.php
index.php
README.txt
rtl.css
screenshot.png
style.css
editor-style.css
theme.json

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().

Top ↑

Including CSS for block styles

In addition to wp_enqueue_style() that you can read about in the theme basics chapter, you can use wp_enqueue_block_style() to enqueue styles for blocks. wp_enqueue_block_style() requires WordPress version 5.9.

A key part of creating block themes is performance. With wp_enqueue_block_style(), the theme only loads the CSS for the selected block when the block is used on the page.
The additional style is loaded in the editor and the front, after the block style provided by WordPress and Gutenberg. You can use this method to add block styles that you can not add via theme.json. For example, media queries.

This code example changes the size and text color of the date in the latest comments block. Because this is a time HTML element that is nested inside other HTML elements, it can not be styled using theme.json.

First, create a new CSS file with the name of the block: latest-comments.css.
Where you place the file depends on how you organize your theme files. In the example, the file is placed inside the folder assets/CSS/blocks.

The CSS class for the time element is wp-block-latest-comments__comment-date. The prefix and the block name are followed by the partial, separated by two underscores.
– You can read more about the naming convention for the block editor in the coding guidelines.

The text color and font size are added with CSS custom properties that are generated from theme.json:

.wp-block-latest-comments__comment-date {
	color: var(--wp--preset--color--primary);
	font-size: var(--wp--preset--font-size--small);
}

Next, enqueue the block style inside the themes setup function.

The block name is placed inside an array to load more than one block style.
A foreach loop walks through each block in the array and creates a handle, src (source), and path argument.
wp_enqueue_block_style() then enqueues the file using the block name and argument:
wp_enqueue_block_style( “prefix/blockname”, $args );

In the code example, the prefix is “core” since the style is for a core block. When you style blocks from plugins, you need to adjust the prefix.

function myfirsttheme_setup() {
	/*
	 * Load additional block styles.
	 */
	$styled_blocks = ['latest-comments'];
	foreach ( $styled_blocks as $block_name ) {
		$args = array(
			'handle' => "myfirsttheme-$block_name",
			'src'    => get_theme_file_uri( "assets/css/blocks/$block_name.css" ),
			$args['path'] = get_theme_file_path( "assets/css/blocks/$block_name.css" ),
		);
		wp_enqueue_block_style( "core/$block_name", $args );
	}
}
add_action( 'after_setup_theme', 'myfirsttheme_setup' );

Top ↑

Including JavaScript

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