Block themes

A block theme is a type of WordPress theme built using blocks. You can edit all parts of a block theme in the Site Editor.

WordPress supports block themes from version 5.9 and with limited support in version 5.8 with the Gutenberg plugin. Together with the Styles interface, block themes are part of full site editing. They are sometimes called full site editing themes. Learn about the background to full site editing.

You may also be interested in reading the support article about block themes.

In this part of the handbook, you will learn about:

  • The differences between classic themes and block themes
  • Block theme setup
  • Templates and template parts
  • The theme.json configuration file
  • Converting classic themes to block themes

Prerequisits for this chapter: Theme Basics

The benefits of block themes The benefits of block themes

Why should you create block themes? While WordPress continues to support classic themes, block themes are built to improve scalability and performance.

  • Block themes enhances loading performance by loading styles only for rendered blocks on a page
  • Block themes are not required to manually enqueue stylesheets for both front-end and editors
  • Theme.json handles all aspects of add_theme_support()
  • Accessibility features such as Skip to content, keyboard navigation, and landmarks are generated automatically without adding additional code
  • With a block theme, the user can edit all parts of their website without code
  • By using the Styles interface, users can customize colors and typography for the website and for the blocks

Top ↑

Differences and similarities between classic themes and block themes Differences and similarities between classic themes and block themes

Many concepts and features are the same for both classic and block themes, and in some cases, the handbook will refer to a chapter about classic themes.

For theme developers that are accustomed to creating classic themes, there is a comparison table:

Classic themes:Block themes:
Uses PHP files to display parts and content.Uses HTML files to display blocks.
Uses PHP files as a fallback if WordPress can not find the HTML file.
single.html is the equivalent of using single.php.
Uses the template hierarchyUses the template hierarchy
Uses PHP functions such as template tags to display contentUses blocks for everything.
The post content block is the equivalent of using the_content().
Use PHP functions to make text translatableText in HTML files is not translatable.
Block patterns can use PHP functions to make text translatable.
Uses PHP functions for if/else conditionalsUses block settings to achieve different results
Uses the loop to display different posts and post types Uses the query block and the post template block
Can use widget areas (sidebars) and widgetsUses blocks instead of widgets. Widgets included in WordPress have been converted to blocks.
Can use the CustomizerUses the Site Editor. Can optionally enable the Customizer menu
Must register a navigation menu to include a menuUses the navigation block
Can register a custom headerUses blocks to fully customize site headers including images
Can register a custom logoUses the site logo block
Can enqueue custom CSS and scriptsCan enqueue custom CSS and scripts but relies more on blocks and the theme.json configuration file
Can use theme.json, but theme authors need to enqueue the styles for the front.Can use theme.json, and the styles are enqueued automatically to the editor and front
Can place template files in the root directoryPlaces template files in the templates folder
Can place template parts in any directoryPlaces template parts in the parts folder
Can not create and edit site templates like 404 and archive pages in the Site EditorCan create and edit site templates like 404 and archive pages in the Site Editor
Can create and edit block templates in the Template Editor with theme supportCan create and edit block templates in the Template Editor