Introducing Carbon Fields v3

For better or worse, WordPress 5.0 was released on Dec 6th, 2018 introducing the new block-based Gutenberg editor as an effective update. An update whose timing did not find the WordPress community completely united upon. However, it is certainly one that everyone within the ecosystem now has to adapt to.

For the past few months, we’ve been focusing our efforts on making Carbon Fields fully compatible with Gutenberg. We’ve added API for creating dynamic blocks, so you can use the same familiar field definition syntax to create rich Gutenberg blocks.

Today we release Carbon Fields version 3 which is available for install via Composer:

composer require htmlburger/carbon-fields

Creating Blocks

In Carbon Fields v3, you will see a new type of container called block. It allows developers to define blocks, as follows:

<?php
use Carbon_Fields\Block;
use Carbon_Fields\Field;

Block::make( 'Flight' )
    ->add_fields( [
         Field::make( 'map', 'from' ),
         Field::make( 'date_time', 'departure_timestamp' ),
         Field::make( 'map', 'destination' ),
         Field::make( 'date_time', 'arrival_timestamp' ),
     ] )
     ->set_render_callback( function( $flight ) {
         ?>
            <p>
                Flight departs
                from <?php echo esc_html( $flight['from']['address'] ) ?> at
                <?php echo $flight['departure_timestamp'] ?>
                and arrives
                to <?php echo esc_html( $flight['destination']['address'] ) ?> at
                <?php echo $flight['arrival_timestamp'] ?>
            </p>
         <?php
     });

From the user’s perspective, here is how this process goes:

You can read more about the block container in the documentation.

post_meta vs block containers

post_meta and block containers are quite different in purpose, as well as the way they store data.

The post_meta containers allow the user to edit meta information below the post body and store that data in the wp_postmeta.

They work in a similar way as in the classic edit screen:

The block containers, on the other hand, are used for a fundamentally different purpose. The values entered inside are stored in JSON objects within the HTML comments in the post_body instead of the wp_postmeta table. This allows users to add multiple copies of each block.

Having cleared up the difference, we could say that block containers are more of glorified shortcodes rather than replacements for the post_meta containers.

Custom fields for post revisions

Carbon Fields v3 introduces custom fields for post revisions, as well. This feature allows users to compare different custom fields’ values in the revision browser. It also allows previewing changes on the front end which were made in the custom fields.


Being first-row spectators of the development journey of WordPress sparks our excitement about what the future holds. Meanwhile, we’ll keep giving our best to maintain CarbonFields as one helpful tool in the hands of fellow developers.

11 Responses

  1. You guys are awesome!

    Thanks for this hard work, I already loved v2 but this v3 looks super promising. Excited to try it out!

  2. Alessandro Tesoro says:

    Thanks a lot for your hard work 🙂

  3. Steve Ryan says:

    Looks great everyone. Thanks for your hard work and for your contribution to the open source community. 🙂

    Any thoughts on when the release will move from release candidate to finalized product?

    … as you alluded to in your opening paragraph above, being able to plan for a firm release date is an important decision for those who have themes and plugins that rely on Carbon Fields.

    • Carbon Fields says:

      We plan to release a stable version next week, before the Christmas holidays. If that date slips, we’ll release in the first week of January.

  4. Nabil says:

    I just want to say Thank you very much , i really appreciate your hard work and dedication.

  5. Alberuni Azad says:

    I loved it and assuming it will be so much popular near future 🙂

  6. Keep up the great work 🙂

  7. So hey… have I expressed how much I love each and everyone who was involved in creating this fantastic project? Whenever I connect and meet with a new WordPress developer, I become giddy with excitement because of the hidden secret they’ve been missing out on.

    Wouldn’t you know that EVERY person I’ve told has transitioned from other libraries straight to Carbon Fields?

    Happy to bring the beers by next time I’m in town. It’s the least I could do.

  8. Newbie question:L Can I use CF to query a database table other than the WordPress ones?

    TIA, Helmar

  9. Hi, just wanted to tell you, I enjoyed this blog post.
    It was helpful. Keep on posting!

Excited about Carbon Fields? Spread the word!