It's almost a year since Gutenberg was born. There was a lot of concerns about this editor, especially the compatibility with meta boxes. We have an in-depth article on this topic half a year ago. Since then, Gutenberg has significant changes and in this article, we want to update the compatibility between Meta Box and Gutenberg so that users are safe using Meta Box in the future.

Update on May 22, 2018 - Meta Box and all extensions are now fully compatible with Gutenberg. Read below for details.

Meta Box 4.14.0 has been released today and is fully compatible with Gutenberg. Although, there are only two Gutenberg's bugs that cause the file, image and wysiwyg fields not working (updated May 22, 2018 - all fields are now working, see below for details). Unfortunately, these are Gutenberg's bugs and they affects all custom field plugins. Hopefully, they are fixed soon. Details are provided below.

This is the edit screen with both Meta Box and Gutenberg activated (click to enlarge):

meta box is now compatible with Gutenberg

Overview Of Issues Between Gutenberg And Meta Boxes

Not only the Meta Box plugin, but any plugin that uses custom fields will also have to deal with Gutenberg compatibility issues. This is the hottest technical issue since Gutenberg was introduced. It got over 170 comments discussed on Github.

Basically, when Gutenberg was born, the development team temporarily removed the area for meta boxes and custom fields. At the time, Gutenberg was the only proof-of-concept for content creation.

Later, there was a UI proposal for the meta box. The meta boxes are rendered at the bottom of the page, below the content section. In Gutenberg version 1.5, meta boxes are displayed via an iframe. However, this approach has encountered objections from many developers.

The developer team then changed the way the meta box was displayed and worked in Gutenberg. And now this method works pretty well.

How Gutenberg Makes Meta Boxes Work?

Gutenberg completely replaces the editing screen and uses JavaScript (React) to render the elements. So the PHP hook for the meta box does not work the same way.

To make the meta boxes work, Gutenberg does the following:

Displaying Meta Boxes

Since there are no PHP hooks running on the page, Gutenberg uses a little trick. It runs the add_meta_boxes and add_meta_boxes_{post post_type} hooks in admin_head so that developers can register the meta boxes. In admin_head the PHP code still works normally. Therefore, developers can register the meta box without any problem.

Then, Gutenberg calls the do_meta_boxes hook to display these meta boxes. Gutenberg will catch their output into its buffer and flush them below the editor.

Saving Custom Fields' Values

The current process of saving custom fields' values is as follows: Press Publish button → the post form is submitted submit → WordPress saves the data and runs the save_post hook → meta boxes hook on that and save the custom fields.

However, in Gutenberg, data is saved via JavaScript thanks to the REST API. There will be no save_post hook in the REST API for meta boxes to hook to.

To fix this problem, after saving the post data via REST API, Gutenberg gets all values ​​of custom fields (thanks to the jQuery.serialize() function) and sends a POST request to post.php, mimic the form submit request. Then WordPress will think that it is a normal submit form request and proceed to save the post data as normal. As a result, meta boxes can store their data.

For technical details about how Gutenberg works with meta boxes, see here.

Meta Box Plugin And Gutenberg

At the beginning time of Gutenberg, when it did not support meta boxes, we encountered many difficulties in ensuring backward compatibility. At that time, the Meta Box development team chose to learn at JavaScript ES6+ and React deeply before coding.

When Gutenberg supported meta boxes without using iframes, we made a small test and found that the custom fields of Meta Box worked very well with Gutenberg. We have published this video on Facebook and Twitter and received a lot of positive feedback:

We then proceeded to check all custom fields and Meta Box features. The results are really good - Gutenberg works well with most custom fields. And we are pretty sure that in 90% of cases, Meta Box and Gutenberg work well together.

Here are some technical issues we encountered when working with Gutenberg.

Styling For Gutenberg

The main problem Meta Box encountered with Gutenberg is the style of custom fields. Gutenberg has some different styles, so some CSS need to be updated.

Updating CSS for the custom fields is now completed and it works both with the classic editor and Gutenberg. This screenshot demonstrates some Meta Box's custom fields in the Gutenberg editor:

Meta Box and Gutenberg compatibility

File Upload Field

Updated April 6th, 2018: This bug is fixed!

Another problem with Gutenberg is the file and image fields. These fields use <input type="file" /> and do manual processing of the file upload, not using the Media Library (do not confuse them with file_advanced and image_advanced which use Media Library for upload).

Unfortunately, Gutenberg has not yet supported the file upload via <input type="file" />. The reason is that Gutenberg only collects data of custom fields through jQuery.serialize() and sends it via POST. Therefore, it only handles the normal fields without processing the upload fields.

This is a Gutenberg bug and we have created an issue on Gutenberg repo. Hopefully, the development team will fix this soon.

1. This bug affects only the file and image fields. Other upload fields such as file_upload, file_advanced and image_advanced still work properly.
2. This bug affects all plugins (not just Meta Box) that use custom upload via <input type="file">.

Editor Field

Updated May 22th, 2018: This bug is fixed!

Another problem we discovered during testing was that Gutenberg completely removed TinyMCE from the editing screen. Therefore, the custom field wysiwyg (editor) doesn't work because the JavaScript is not working.

We think this is a Gutenberg bug because these editors are rendered through the WordPress wp_editor() function. So we also created another issue and hopefully it will be fixed soon.

Again, this bug affects all plugins (not just Meta Box) that use TinyMCE for the editor field.

Other features of Meta Box such as clone, groups, columns, tabs, etc are all working well.


With this update, we hope Meta Box users will be able to use the plugin in the long term. Although there are some bugs, we hope the Gutenberg team will fix them soon so that it does not affect our code.

As planned, there is a month until Gutenberg is merged into the core, but you can install it now and try it with the Meta Box plugin. If you find any bug, please let us know so that we can fix it as soon as possible. And don't forget to update Meta Box today!

13 thoughts on “Meta Box is Now Compatible with Gutenberg

  1. This is totally AWESOME!!! Great work guys. Thanks for staying ahead of the game. This is going to help boost my new theme into the stratosphere 😉

  2. Keep going! Good luck with the opened issues, defend them as hard as you can! Fight for your share, you have supported WP all the years and made it what it is. Some seem to have different plans for future of you/ACF/others,

  3. This is great news. I was worried as I have been using Meta Boxes heavily in one of my theme, this gives me relief for future compatibility. I will test and report back if I find any other issues not mentioned here. Thank again for all your hard work.

    1. You can use the [rwmb_meta] shortcode to output field value into a block. Gutenberg already supports rendering shortcodes AFAIK.

  4. Ok, that sounds that it works... I'll try then. But I suppose that we have to use it within javascript and with the id of the field in parameters?

    1. I think just pasting the shortcode with the ID of the field will work. Haven't tried it yet, but I saw the demo of Gutenberg that auto renders the shortcode.

  5. "To fix this problem, after saving the post data via REST API, Gutenberg gets all values ​​of custom fields (thanks to the jQuery.serialize() function) and sends a POST request to post.php, mimic the form submit request."

    As of WP 5.0 with Gutenberg, is this still true? The $_POST array is empty when I check requests to post.php on post publication.

    1. It's still true. There are actually 2 POST requests, one from Gutenberg to save post content, and 2nd to save meta box data.

  6. Hey,
    My page is heavy on custom fields, but for Preview Gutenberg is not saving meta, is there a way to fix that? With WP classic editor everything is fine.

Leave a Reply to God Jul Cancel reply

Your email address will not be published. Required fields are marked *