WordPress 5.9 introduced a new way to build websites: Full Site Editing. It was a turning point for WordPress users because it completely changed the way WordPress themes are built and work.
The introduction of FSE also introduced a distinction between themes that fully support the new site-building features, also known as Block Themes, and the traditional PHP-based themes, which we now call Classic Themes.
Over time, many features built for Block Themes have been extended to Classic Themes. This has resulted in a third category of themes, Hybrid Themes, that are still built with the logic and structure of Classic Themes but with support for various features designed for Block Themes.
This article explores Hybrid Themes, their key features, how developers can enhance them, and when to choose them over Block Themes.
Let’s dive in!
Classic or Hybrid Themes?
Before the introduction of Block Themes with Twenty Twenty-Two and WordPress 5.9, there were no such things as Classic Themes. The term came about to distinguish them from Block Themes. Classic Themes are all WordPress themes without support for block features.
Today, it is not easy to find pure Classic Themes because, since 5.9, these themes have been enhanced with many features built for Block Themes, making the editing and design experiences of the two categories of themes closer and closer over time.
That being said, the way you work with Hybrid Themes is still different from Block Themes.
Basic features of Hybrid Themes
With Hybrid Themes, your site can take advantage of the editing capabilities of the WordPress block editor while remaining compatible with traditional WordPress plugins and features such as widgets, menus, and page templates.
The WordPress Customizer
Hybrid Themes typically support the WordPress Customizer, a visual configuration environment that lets you fine-tune the appearance of your WordPress website and preview your changes in real-time.
The Twenty Twenty-One default theme is a good example of a hybrid theme providing the most common Customizer settings, including Site Identity, Colors & Dark Mode, Background Image, Menus, Widgets, Homepage Settings, and more.
Themes can register specific Customizer controls, so functionality varies by theme. The following image shows the Customizer for Neve, a lightweight hybrid theme from ThemeIsle.
Themes can also register advanced features to give users granular control over specific aspects of site design. Neve, for example, provides a powerful builder for creating site headers and footers.
Block widgets
Hybrid Themes allow you to customize Widget Areas using blocks, thanks to the block-based widgets editor. It was first introduced with WordPress 5.8, and you can try it with any Classic Theme using widgets.
The Widget Editor interface is similar to the Post Editor interface. The following image shows an Image block in the Footer widget area of the Twenty Twenty-One theme.
Classic widgets such as Categories, Archives, Recent Posts, or Recent Comments are still supported in Hybrid Themes. The Widget Editor complements the classic WordPress widgets by allowing users to create their own through its block-based interface.
Style book and block patterns
With the recent changes introduced with WordPress 6.8, Hybrid Themes that support editor styles can use the Style Book, a visual interface that allows users to preview any block that can be used on their websites without having to use those blocks in their content.
You can access the Style Book in Hybrid Themes from Appearance > Design > Styles.
The following image shows the Style Book for the Kadence hybrid theme.
In the same interface, you can browse and manage Patterns.
For Hybrid Themes that support them, patterns are available for use in the Post Editor, which is enabled by default on all WordPress installations since 5.0, unless you have disabled it with the Classic Editor plugin.
Theme structure: A developer’s overview
Classic and Block Themes are not only different in terms of functionality for the final user. They are also different from a structural point of view.
Classic Themes
Classic Themes rely on a few key files, the most important of which is the style.css file. It provides the theme’s metadata and determines the site’s appearance on the front end.
In addition to the theme style sheet, Classic Themes typically have a functions.php file used to build the theme’s functionality and support.
Classic Themes also rely on PHP templates that define the structure of a page and its main areas: header, body, sidebars, and footer. When a user visits a post or page, WordPress determines which template to use to render the content on the screen according to a strict system of rules known as the template hierarchy. Most commonly used templates include index.php, page.php, single.php, and many others.
Classic Themes may use specific PHP functions (action and filter hooks), which are executed at specific moments in the life of WordPress, enabling developers to extend a theme’s functionality using PHP code in the functions.php file of a child theme.
You may guess that customizing a classic theme is particularly hard for users without coding skills.
Block Themes
Block Themes also need a style.css to provide WordPress with the theme metadata, but they strongly rely on a theme.json file, a configuration file that defines global styles and settings for a theme. It contains a JSON object whose properties define the initial settings needed to create the layout and define the appearance of the site’s pages.
Block Themes also use templates and template parts, but these are structurally different from classic theme PHP templates. In Block Themes, templates and template parts are HTML files containing specific markup and JSON objects. For example, consider the home.html template of the Twenty Twenty-Five default theme:
This template consists of structured elements in the form of HTML tags and comments. Comments may refer to other typical elements of a block theme, such as template parts and patterns, which are composed of blocks or other nested elements.
Adding block features to Hybrid Themes
As we mentioned above, with Classic Themes, you need to add custom code to alter a site’s layout or functionality, often involving template files or functions.php. In contrast, Block Themes empower non-developers with greater control over site layout and appearance.
Hybrid Themes offer fewer block features than Block Themes but may still provide enhanced layout and style control through patterns and global styles.
Let’s explore some powerful block features you can integrate into your classic theme and learn how to implement them effectively.
Global Styles
WordPress 5.8 introduced Global Styles, a visual interface that allows users to control the look and feel of their website from a centralized interface, and developers to control the styles of their WordPress websites through a theme.json file.
To enable this feature in your hybrid theme, simply add a theme.json file to the theme’s root folder. Let’s look at some of the key features that you can add to your hybrid theme with theme.json.
Typography
Let’s say you want to add support for three font families to your classic theme. In this example, we will use Twenty Twenty-One.
First, create a fonts folder under assets and upload some fonts of your choice. We’re adding three fonts: Manrope, Fira Code, and Beiruti. You can get these fonts from the Twenty Twenty-Five theme.
Open your text editor and create the following theme.json:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"settings": {
"layout": {
"contentSize": "768px",
"wideSize": "1024px"
},
"typography": {
"fontFamilies": [
{
"name": "Manrope",
"slug": "manrope",
"fontFamily": "Manrope, sans-serif",
"fontFace": [
{
"src": [
"file:./assets/fonts/manrope/Manrope-VariableFont_wght.woff2"
],
"fontWeight": "200 800",
"fontStyle": "normal",
"fontFamily": "Manrope"
}
]
},
{
"name": "Fira Code",
"slug": "fira-code",
"fontFamily": ""Fira Code", monospace",
"fontFace": [
{
"src": [
"file:./assets/fonts/fira-code/FiraCode-VariableFont_wght.woff2"
],
"fontWeight": "300 700",
"fontStyle": "normal",
"fontFamily": ""Fira Code""
}
]
},
{
"name": "Beiruti",
"slug": "beiruti",
"fontFamily": "Beiruti, sans-serif",
"fontFace": [
{
"src": [
"file:./assets/fonts/beiruti/Beiruti-VariableFont_wght.woff2"
],
"fontWeight": "300 700",
"fontStyle": "normal",
"fontFamily": "Beiruti"
}
]
}
]
}
}
}The settings.typography.fontFamilies property allows you to register any number of custom font families. For each font, you’ll need to declare the following properties:
name: A required human-readable title for the font family.slug: A required slug for the font family. It will be appended to a generated CSS custom property:--wp--preset--font-family--{slug}.fontFamily: A required value that will map to the CSS font-family value.fontFace: An optional array of font faces that are mapped to the@font-faceCSS at-rule. You only need this with custom web fonts.
Save your theme.json and navigate to your WordPress dashboard. Create a new post or page, add a paragraph with a sample text, and open the block sidebar. Click on the Typography Options button and select Font. You should find options for the font families you have just added to your theme.
The following images show what the sidebar of the Paragraph block looks like before and after adding the theme.json shown above.
Global style properties vary by theme. Apart fromtypography, commonly supported properties allow you to control color palette, layout, and custom styles. The following examples have been tested on Twenty Twenty-One.
Color palette, gradients, and duotone filters
You can add support for custom colors using the settings.color property at the theme or individual block level. For example, the following code adds two colors to the default palette:
settings: {
"color": {
"palette": [
{
"name": "Dark blue",
"slug": "dark-blue",
"color": "#1e73be"
},
{
"name": "Bright green",
"slug": "bright-green",
"color": "#81d742"
}
]
},
}You can use the settings.color.palette property to register as many colors as you want.
You can also add support for gradients and duotone filters:
settings: {
"color": {
"gradients": [
{
"gradient": "linear-gradient(135deg, #0073e6, #8fceff)",
"name": "Clear Sky",
"slug": "clear-sky"
},
{
"gradient": "linear-gradient(to right top, #ff8c00, #ff0080)",
"name": "Vivid Sunset",
"slug": "vivid-sunset"
}
]
}
}
settings: {
"color": {
"duotone": [
{
"colors": [ "#0A2F51", "#F5D04E" ],
"name": "Deep Sea Gold",
"slug": "deep-sea-gold"
},
{
"colors": [ "#3A0CA3", "#FFB703" ],
"name": "Purple Amber",
"slug": "purple-amber"
},
{
"colors": [ "#1B4332", "#BAE6C4" ],
"name": "Forest Mist",
"slug": "forest-mist"
},
{
"colors": [ "#000000", "#FFFFFF" ],
"name": "Black and White",
"slug": "black-and-white"
}
]
}
}
Layout
You can also customize the default layout settings. The settings.layout property allows you to set the default content width and wide alignment width. Here is an example:
"settings": {
"layout": {
"contentSize": "768px",
"wideSize": "1024px"
}
}For a more in-depth overview oftheme.json, check out our comprehensive tutorial on theme.json and the official WordPress documentation.
Block style variations
First introduced with WordPress 5.3, block style variations allow developers to create alternative styles for specific blocks.
In short, block styles are CSS classes added to the wrapper element of a block in the form .is-style-{name}.
Block style variations appear in the Styles panel of the block sidebar and allow you to select a style for the block with a single click.
You can register your block style variations in several ways.
First, you can register block styles using the PHP register_block_style() function. For example, you could register the following style variation in your theme’s functions file:
if ( function_exists( 'register_custom_block_style' ) ) {
register_block_style(
'core/image',
array(
'name' => 'custom',
'label' => __( 'Custom', 'text-domain' ),
'inline_style' => '.wp-block-image.is-style-custom img { border-radius: 12px; }',
)
);
}
add_action( 'init', 'register_custom_block_style' ); register_block_style() accepts two arguments:
$block_name: The name of a block type or an array of block types$style_properties: An array containing the style properties. In this example, we usedname,label, andinline_style.
The code above generates a block style variation with a single CSS property. Once this code is added to the functions.php file of your theme or child theme, a button displays in the block styles panel to allow the user to set the style with a single click.
The following image shows the block style variation in the front end. The theme is still Twenty Twenty-One.
You can add your inline styles in your PHP code, as in the above example, but your code can quickly become difficult to maintain as styles become more complex and elaborate. In these cases, you can register the style variation as we saw earlier but define the styles in your theme.json file.
In the following example, we create a Dark blue style variation for the Heading block.
First, register the style variation in the theme’s functions file:
add_action('init', 'register_block_style_labels');
function register_block_style_labels() {
$block_types = ['core/heading'];
if (function_exists('register_block_style')) {
foreach ($block_types as $block_type) {
register_block_style(
$block_type,
array(
'name' => 'dark-blue-bg',
'label' => __('Dark Blue', 'twentytwentyone')
)
);
}
}
}Next, define the variation styles in your theme.json file:
"settings": {
"styles": {
"blocks": {
"core/heading": {
"variations": {
"dark-blue-bg": {
"color": {
"background": "#2860a6",
"text": "#ffffff"
},
"spacing": {
"padding": {
"top": "0.3em",
"right": "0.4em",
"bottom": "0.3em",
"left": "0.4em"
}
}
}
}
}
}
}
}Now, your theme users can choose between two style variations for the Heading block, as shown in the following image.
Block variations
Block variations are alternate versions of any registered block. While block style variations (or block styles) are customized versions of a block style that users can add to content with a single click, block variations are alternate versions of a block’s settings. These allow users to quickly insert a block with pre-configured settings without having to set the same configurations for each block instance.
The Block Variations API allows Hybrid Themes to register block variations via JavaScript. In the simplest cases, creating a script and enqueuing it may do the trick, but if you work a lot with JavaScript and Gutenberg blocks, you may want to incorporate build tools into your workflow. (Suggested reading.)
Suppose you want to create a block variation with a set of pre-configured options so that your variation can be inserted quickly into your posts or pages with minimal additional configuration required.
The first step is to create an empty JavaScript file and load it into the editor. You will need to enqueue it in your theme’s functions.php file using wp_enqueue_script() and the enqueue_block_editor_assets action hook.
add_action( 'enqueue_block_editor_assets', function () {
wp_enqueue_script(
'my-block-variations',
get_theme_file_uri( 'assets/js/block-variations.js' ) . '?cache_bust=" . time(),
array(
"wp-blocks',
'wp-dom-ready',
'wp-i18n',
'wp-edit-post'
),
wp_get_theme()->get( 'Version' ),
true
);
} );In the code above, we used ?cache_bust=" . time() to add a unique timestamp to the URL of block-variations.js (e.g., block-variations.js?cache_bust=1698765432). This is particularly useful during development, as it ensures that the browser, server, or CDN always loads the latest version of the script, preventing an outdated cached version from blocking the display of changes.
Next, you need to register your block variation in your script using the registerBlockVariation function provided by the Block Variations API.
Here is the function signature:
const registerBlockVariation = ( blockName, variation )blockName: The name of the block (i.e.,core/query.)variation: An object describing a variation for the block type.
The variation object can include any of the following parameters:
name: (string) A unique identifier of the variation.title: (string) A human-readable variation title.description: (string) A detailed description.category: (string) A category used in search interfaces.keywords: (Array) An array of terms that help users discover the variation.icon: (WPIcon) An icon to display in the block inserter.isDefault: (boolean) Whether the current variation is the default one. Defaults to false.isActive: (Function/Array) A function or an array of block attributes used to determine if the variation is active when the block is selected. WithoutisActive, WordPress would not know how to distinguish your variation from a standard block or other variations, causing inconsistent behavior in the editor.attributes: (Object) Attribute values that override block defaults.innerBlocks: (Array[]) Initial configuration of nested block.example: (Object) Structured data for the block preview. Set to undefined to disable the preview.scope: (WPBlockVariationScope[]) The list of scopes where the variation is applicable. When not provided, it assumes all available scopes. Available options areblock,inserter, andtransform. It defaults toblockandinserter.
Now you can add the JavaScript to the block-variations.js file:
wp.blocks.registerBlockVariation( "core/heading', {
name: 'custom-centered-text',
title: 'Custom Centered Text',
description: 'This is a block variation with custom attributes.',
attributes: {
level: 2,
textAlign: 'center',
placeholder: 'Add your text here',
style: {
color: {
text: '#1e73be',
background: '#81d742'
}
}
},
isActive: ( blockAttributes ) => {
return (
blockAttributes.level === 2 &&
blockAttributes.textAlign === 'center' &&
blockAttributes.style?.color?.text === '#1e73be' &&
blockAttributes.style?.color?.background === '#81d742'
);
},
icon: 'airplane',
scope: [ 'inserter' ]
} );This code adds a new block type with an airplane icon to the block inserter. When you click on the airplane, a new Heading block variation gets added to the page with your custom settings. We set the header level (H2), centered the text, set a placeholder, and defined the header’s text and background colors.
Note: For this code to work as expected, make sure that your hybrid theme adds support for editor features such as 'editor-color-palette', editor-styles, and others. For a more comprehensive list of supports, check the Block Variations API.
Block patterns
Block patterns are prebuilt groups of blocks you can add to your content and customize using the block editor’s interface.
Block Themes usually provide a variable number of block patterns you can add to your content directly from the block inserter. Hybrid Themes can add support for patterns so that classic theme users can benefit from this powerful feature.
You can create a patterns folder in your theme’s root and include your block patterns, or you can register them in your theme’s functions.php or other .php files.
To keep things in order, you can create a file inc/block-patterns.php and include it in your theme’s function.php with the following code:
require get_template_directory() . '/inc/block-patterns.php';Once done, you can build your pattern in the editor, copy the code, and register your pattern and pattern category in inc/block-patterns.php using register_block_pattern_category and register_block_pattern() functions:
if ( function_exists( 'register_block_pattern_category' ) ) {
function my_hybrid_theme_register_block_pattern_category() {
register_block_pattern_category(
'myhybridtheme',
array( 'label' => esc_html__( 'My Hybrid Theme', 'myhybridtheme' ) )
);
}
add_action( 'init', 'my_hybrid_theme_register_block_pattern_category' );
}
if ( function_exists( 'register_block_pattern' ) ) {
function my_hybrid_theme_register_block_pattern() {
// My pattern
register_block_pattern(
'myhybridtheme/huge-heading',
array(
'title' => esc_html__( 'Huge heading', 'myhybridtheme' ),
'categories' => array( 'myhybridtheme' ),
'viewportWidth' => 1440,
'blockTypes' => array( 'core/heading' ),
'content' => '' . esc_html__( 'A simple Heading in a pattern', 'myhybridtheme' ) . '
',
)
);
}
add_action( 'init', 'my_hybrid_theme_register_block_pattern' );
}You can preview your pattern in your WordPress dashboard under Appearance > Design > Patterns > My Hybrid Theme and use it in your content.
You can also duplicate and export your pattern and import it into other WordPress websites.
Template parts
Although Hybrid Themes uses the classic PHP templates and template parts, you can add support for block template parts in your theme’s functions.php file:
function my_hybrid_theme_setup() {
add_theme_support( 'block-template-parts' );
}
add_action( 'after_setup_theme', 'my_hybrid_theme_setup' );Once you have added support for template parts, you can include any template part in any template file of your hybrid theme using the block_template_part function.
Let’s look at a practical example. Start by creating a /parts folder in your theme’s root and uploading a footer.html file into it. For this example, we copied the footer from the Twenty Twenty-Five theme:
Now you can include this template part in a classic template with the block_template_part function:
You can, for example, include it in the footer.php file of Twenty Twenty-One. The following image shows the result on the screen.
You can also include template parts into a block template using the following code:
You can, for example, copy the code of the page.html template from Twenty Twenty-Five:
Save this template in your /templates folder and call it page.html. WordPress will automatically load it according to the template hierarchy. This template will automatically include header.html and footer.html template parts from your hybrid theme’s /parts folder.
When to choose Hybrid Themes over Block Themes
A Hybrid theme may be the best option in the following scenarios:
- When you want to use some modern features of Block Themes without completely restructuring an existing site.
Hybrid Themes allow you to take advantage of block features such as the block editor, global styles, and block patterns. Hybrid Themes also support block editor APIs such as the Block Bindings API, Interactivity API, and HTML API. This means that you can create modern websites without having to go through a complex migration. - When you want to maintain compatibility with classic plugins or widgets but do not want to give up some powerful features of Block Themes.
Older versions of some plugins may have compatibility issues with Block Themes, such as older versions of Contact Form 7, NextGEN Gallery, Custom Post Type UI, and other plugins. Although it is recommended to update plugins to the latest versions to prevent security vulnerabilities, some WordPress sites may have older versions of a plugin installed. If you are not yet ready to upgrade all your plugins, you might consider installing a hybrid theme. - When you are trying to find the best compromise between design and performance.
Some popular Hybrid Themes are optimized for speed and can provide significantly better performance than Block Themes. Yet they support the no-code/low-code approach of Block Themes providing a better design experience than Classic Themes. Performance-optimized Hybrid Themes such as Neve or Kadence allow you to create modern-looking websites without compromising performance. - When you want a smooth transition to FSE.
Sometimes, the transition from the old to the new design logic can take time, especially when working in teams on large sites, and the learning curve is a concern. A hybrid theme allows your team to experiment with block functionality while maintaining familiar design tools such as the Customizer and classic PHP templates.
However, there are also scenarios where Hybrid Themes are not the best option. For example:
- When site design tools take precedence over overall performance.
When you want to use some features specific to Full Site Editing, such as the Site Editor, full template editing via blocks, and the Global Styles interface, a hybrid theme is not an option because these features are not supported or are only partially supported in Hybrid Themes. - With headless WordPress sites based on the WordPress REST API.
In this scenario, Block Themes are to be preferred because block data are easily exposed via the REST API (see, for example, the endpoint/wp/v2/blocks) or WPGraphQL, where Hybrid Themes could add greater complexity. - When a no-code approach to site building is preferred.
Hybrid Themes do not support template creation or editing via the site editor. Although support for template parts can be added, this support is currently limited, and template management is primarily PHP-based.
The bottom line is that there is no hard and fast rule for choosing between hybrid and Block Themes. It depends on many factors, such as the skills available in your team, the type of site being built, performance requirements, backward compatibility, and much more.
Summary
Full Site Editing and Block Themes have dramatically changed how we build WordPress websites. The block philosophy gives users more power to create complex layouts and fine-tune every aspect of a website.
But if you are not yet ready to make the leap because your site may not be fully compatible with Block Themes or because it requires specific features of a classic theme, Hybrid Themes are an option that allows you to have the best of both worlds by allowing you to use some powerful features of Block Themes while maintaining compatibility with the features of plugins and Classic Themes.
Not to mention performance. Block Themes can be resource-intensive due to extensive block rendering and JavaScript usage. Performance-optimized Hybrid Themes can make your site lighter and perform better by reducing the load of JavaScript needed.
Carlo is a passionate lover of webdesign and front-end development. He has been playing with WordPress for more than 20 years, also in collaboration with Italian and European universities and educational institutions. He has written hundreds of articles and guides about WordPress, published both on Italian and international websites, as well as on printed magazines. You can find him on LinkedIn.
Source link
