Block themes
Topics
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
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
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 hierarchy | Uses the template hierarchy |
| Uses PHP functions such as template tags to display content | Uses blocks for everything. The post content block is the equivalent of using the_content(). |
| Use PHP functions to make text translatable | Text in HTML files is not translatable. Block patterns can use PHP functions to make text translatable. |
| Uses PHP functions for if/else conditionals | Uses 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 widgets | Uses blocks instead of widgets. Widgets included in WordPress have been converted to blocks. |
| Can use the Customizer | Uses the Site Editor. Can optionally enable the Customizer menu |
| Must register a navigation menu to include a menu | Uses the navigation block |
| Can register a custom header | Uses blocks to fully customize site headers including images |
| Can register a custom logo | Uses the site logo block |
| Can enqueue custom CSS and scripts | Can 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 directory | Places template files in the templates folder |
| Can place template parts in any directory | Places template parts in the parts folder |
| Can not create and edit site templates like 404 and archive pages in the Site Editor | Can 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 support | Can create and edit block templates in the Template Editor |