Home/ Documentation/ WordPress/ Blocks/ Hybrid Blocks

Hybrid Blocks

The missing piece to making custom Gutenberg blocks useful in real-world projects.

Hybrid blocks is a new block type (in addition to React and Dynamic PHP blocks), with three huge benefits:

  • No more block recovery.
  • Blocks are always up-to-date across the whole site.
  • Snappy React-based editing experience.

Watch the videos

Watch the video introduction to hybrid blocks to see them in action:

Watch Adam Lowe compare static React blocks, dynamic PHP blocks and the new hybrid blocks and offer advice on what is the best block type for different situations:

The problem

Imagine having a custom Info Card block. The block is implemented as a native React-based block that provides the best editing experience. The block is used on hundreds of posts and pages on the site.

Editing the custom Info Card block in Pinegrow

Now, we decide to slightly change the structure of the block, for example by adding a vertical divider below the title.

We add a hr element under the title

What happens as a result?

First of all, instances of the old Info Card blocks, without the divider, are still displayed on the site.

The updated block is not visible on the site

To update them to the new version, we have to open every single post or page in the editor and recover each block instance.

We need to recover every single instance of the block

Then, we have to save the page.

And resave every post where Info Card blocks appear

For larger sites this could take hours of incredibly boring and repetitive clicking around. Not to mention how prone to errors this would be.

The problem comes from the way blocks are implemented in WordPress. Native React blocks are rendered only at the time the post is saved in the editor. There is no way to run this code on the server and update all block instances on the site. 

In addition, there is no easy option in the WordPress editor to run block recovery automatically.

Current solutions

Block recovery can be avoided by adding a special JavaScript code to the block that handles upgrading the block to the next version. But for custom blocks that are frequently modified doing this requires a lot of attention and effort. And Pinegrow does not support generating such upgrade code automatically.

Even when blocks know how to upgrade themselves, re-saving all posts where blocks are used is required to display the updated block instances on the front-end. This involves finding all block instances on the site and then going through each post and saving it.

Most block libraries use this approach.

Dynamic PHP blocks help, but…

The best solution – when it comes to keeping a large number of block instances up-to-date – is to use dynamic PHP blocks. Such blocks are dynamically rendered each time a page is displayed and are therefore always up to date.

Setting the Block type parameter of the Block action to Dynamic

Also, there is no block recovery in the editor, because WordPress does not save the rendered HTML output of such blocks in the post content.

But the editing experience is clunky. For every change we do, such as typing a character in the input field, the whole block needs to be re-rendered on the server. And content can only be edited in the sidebar, not directly in the editor view.

Clunky editing experience of dynamic blocks

Hybrid blocks – the best of both worlds

Hybrid blocks combine features of both React and PHP blocks: 

  • React is used to edit the block in the editor, thus providing a smooth editing experience. 
  • PHP is used to render the block when it is displayed on the front-end.

The result is powerful and frictionless. No more block recovery, and blocks are always displayed up-to-date, without having to resave posts where they are used.

What’s the catch?

Well, hybrid blocks are a pain to code. Each block needs to be implemented twice: once as a React block and once as a dynamic PHP block.

They are also high maintenance. Every change has to be done on both versions of the block: in React and in PHP. This is a recipe for frustration and errors.

Unless we are using a smart tool that does all the code generation for us.

A tool like Pinegrow.

The easy way to build hybrid blocks

With Pinegrow, the source of the block is HTML code with actions such as Block Attributes added to its elements. All editing of the block happens visually, with HTML and CSS.

When we export the project (a plugin or a theme), Pinegrow generates all PHP and JavaScript files, including React code for blocks. This setup is perfect for generating hybrid blocks.

As usual, we design the block visually with HTML. All we have to do is set the Block type to Hybrid.

On export, Pinegrow generates both the React and PHP code and integrates them together so that the React version is used in the editor and the PHP version is used when displaying the blocks on the front-end. 

Smooth editing experience of a Hybrid block

Whenever we change the block…

Here, we swapped the positions of the inner content and the image

…the up-to-date blocks are displayed on the site, automatically:

The change is immediately visible on the site

There is no overhead for the developer. No need to implement things twice. We get two blocks for the price of one!

The result is as good as it gets – native, custom WordPress blocks that can be used without hassle on real-world projects. You can confidently use such blocks on your client sites, knowing that updating all of them is just one simple Export away.

Are there any drawbacks of Hybrid blocks?

Hybrid blocks (and dynamic PHP blocks) are rendered each time they are displayed, unlike React blocks that are only rendered at the time the post is saved, with the output stored in the post content.

So, using Hybrid and PHP blocks have roughly the same performance as a PHP template, without the same slight gain that you get with a pre-rendered React block. But, the effect of this is negligible. Compared to all the PHP files that are loaded and evaluated when WordPress displays a page, running a couple more PHP scripts for blocks should not make much of a difference. 

Most sites also use some kind of caching solution that completely mitigates this issue.

Getting started with Hybrid blocks

Hybrid blocks are available now in Pinegrow Web Editor 7.6 and in Pinegrow WordPress Plugin PRO 1.0.12. 

The way how blocks are edited is exactly the same as before. The only difference is setting the block type to Hybrid.

This can be done either in Project settings for all blocks in the project…

Setting the default block type in the project settings

…or in Block action on each individual block.

Setting the Block type argument of the Block action to Hybrid

To convert your existing React blocks to Hybrid blocks, open the project in Pinegrow and change the block type to Hybrid. 

Then, export the project and deploy the exported theme or plugin to the server. From that moment on, these blocks will be rendered dynamically. You don’t have to update and save the posts where they are used.

Interactive tutorial

Pinegrow Web Editor and Pinegrow WordPress Plugin come with a built-in tutorial in the Interactive tutorials section on the dashboard:


In general, changing the block type from React to Dynamic or Hybrid can cause strange side-effects on existing block instances on the page.

The one situation that can cause issues is converting a dynamic PHP block with inner content into a Dynamic or Hybrid block. There, the block itself can appear as its own inner content, recursively. The solution is to re-save the post where the block is used.

Also, the classes of the top block elements of block instances can get stuck when block type is changed. The classes get stored in the Additional CSS Classes property of the block. The solution is to remove these classes from the Additional CSS Classes field.

Old unused classes can get stuck when changing the block type from React to Dynamic or Hybrid

Both issues look like WordPress bugs and appear only one time, when the block type is changed.

Have fun with Hybrid blocks and let us know if you encounter any problems.

Last updated on June 29, 2023 at 11:23 am

Print this article