Custom fields for every corner of WordPress

Wonder Fields needs WordPress 6.0 or newer and PHP 7.4 or newer.

1. In your WordPress admin, go to Plugins›Add New›Upload Plugin.
2. Choose wonder-fields.zip and click Install Now. You can also upload the wonder-fields folder to /wp-content/plugins/ by FTP.
3. Click Activate. A Wonder Fields menu appears in the admin sidebar with Field Groups, Post Types, Taxonomies, Options Pages, Tools and Settings.

A field group is a set of fields that appears together on an edit screen. Here is how to add a subtitle and hero image to every page.

1. Go to Wonder Fields›Field Groups›Add New and name the group, for example Hero.
2. Click Add Field. Enter the Label (what editors see) and check the Name (what you use in code, such as subtitle). Choose the field type.
3. Add a second field called hero_image with the Image type.
4. Under Location, choose Post Type is equal to Page.
5. Click Publish. Open any page and the Hero fields are there, ready to fill in.

Location rules decide which edit screens show a group. Rules in the same row must all match (AND). Add a rule group to show the fields when either set matches (OR).

Conditional logic keeps edit screens tidy. Open a field, turn on Conditional Logic, and pick the field and value it depends on.

For example, add a True / False field called has_video, then give an oEmbed field the rule has_video is checked. The video field only appears once the box is ticked. Hidden fields are skipped when the post is validated and saved.

Use the_field() to print a value and get_field() to get it for use in your own markup. Both read from the current post unless you pass a post ID.

<h2><?php the_field( 'subtitle' ); ?></h2>

<?php
$image = get_field( 'hero_image' );
if ( $image ) {
    echo wp_get_attachment_image( $image['ID'], 'large' );
}

// Read from another post.
$price = get_field( 'price', 42 );
?>

All 21 functions: get_field, the_field, get_fields, get_field_object, get_field_objects, update_field, delete_field, have_rows, the_row, get_row, get_row_layout, get_row_index, reset_rows, get_sub_field, the_sub_field, get_sub_field_object, update_sub_field, delete_sub_field, add_row, update_row, delete_row.

Create a Repeater field called team with sub fields name and role. Then loop the rows in your template:

<?php if ( have_rows( 'team' ) ) : ?>
    <ul class="team">
    <?php while ( have_rows( 'team' ) ) : the_row(); ?>
        <li>
            <h3><?php the_sub_field( 'name' ); ?></h3>
            <p><?php the_sub_field( 'role' ); ?></p>
        </li>
    <?php endwhile; ?>
    </ul>
<?php endif; ?>

A Flexible Content field holds rows that each use one of several layouts. Check the layout name for each row and output the right markup.

<?php while ( have_rows( 'sections' ) ) : the_row();

    if ( 'hero' === get_row_layout() ) {
        get_template_part( 'sections/hero' );
    } elseif ( 'gallery' === get_row_layout() ) {
        get_template_part( 'sections/gallery' );
    }

endwhile; ?>

Pass a second argument to say where the value is stored.

Options pages hold values that apply to the whole site, like a phone number or social links. Create one under Wonder Fields›Options Pages, or in code:

wf_add_options_page( array(
    'page_title' => 'Site Settings',
    'menu_slug'  => 'site-settings',
) );

Then set a field group's location to Options Page is equal to Site Settings, and read values with get_field( 'phone', 'option' ).

Register the block in functions.php, create a field group with the location Block is equal to Testimonial, and write the template.

add_action( 'init', function () {
    wf_register_block_type( array(
        'name'            => 'testimonial',
        'title'           => 'Testimonial',
        'icon'            => 'format-quote',
        'render_template' => 'template-parts/blocks/testimonial.php',
    ) );
} );

<blockquote class="testimonial">
    <p><?php the_field( 'quote' ); ?></p>
    <cite><?php the_field( 'author' ); ?></cite>
</blockquote>

The block is registered as wf/testimonial. Templates also receive $block, $content, $is_preview and $post_id.

Groups registered in PHP load fast and can't be changed by accident in the admin. Tip: build a group in the admin first, then use Tools›Generate PHP to get this code for you.

add_action( 'wonder_fields/include_fields', function () {
    wf_add_local_field_group( array(
        'key'      => 'group_hero',
        'title'    => 'Hero',
        'fields'   => array(
            array(
                'key'   => 'field_hero_title',
                'name'  => 'hero_title',
                'label' => 'Title',
                'type'  => 'text',
            ),
        ),
        'location' => array(
            array(
                array( 'param' => 'post_type', 'operator' => '==', 'value' => 'page' ),
            ),
        ),
    ) );
} );

• Local JSON. Create a wonder-fields-json folder in your active theme. Field groups, post types, taxonomies and options pages are saved there as JSON whenever you save them.
• Sync. When a JSON file is newer than the database copy, the Field Groups list shows Sync available. Click it to update the site.
• Export and import. Under Wonder Fields›Tools, export groups as a JSON file, import a file on another site, or generate PHP.

// Save JSON to a custom folder.
add_filter( 'wonder_fields/settings/save_json', function () {
    return get_stylesheet_directory() . '/fields';
} );

Turn on Show in REST API in a field group's settings. Its values then appear in a wonder_fields property on /wp/v2 responses, and you can update them by sending the same property back.

{
    "id": 42,
    "title": { "rendered": "About" },
    "wonder_fields": {
        "subtitle": "Meet the people behind it",
        "hero_image": 318
    }
}

Most filters also accept /type=, /name= and /key= variants, so you can target one field type, one field name or one field key.

// Require a subtitle of at least 10 characters.
add_filter( 'wonder_fields/validate_value/name=subtitle', function ( $valid, $value ) {
    if ( strlen( $value ) < 10 ) {
        return 'Please write at least 10 characters.';
    }
    return $valid;
}, 10, 2 );