Creating fields with code

Use code to create custom fields if you want to keep everything in your themes or plugins. This lets you reuse them across websites and put them under version control like Git.

Registering custom fields with PHP

To create custom fields, use the rwmb_meta_boxes filter to register field groups. This filter accepts one parameter - the array of field groups:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
    $meta_boxes[] = [
        'title'      => 'Event details',
        'post_types' => 'event',
        'fields'     => [
            [
                'name' => 'Date and time',
                'id'   => 'datetime',
                'type' => 'datetime',
            ],
            [
                'name' => 'Location',
                'id'   => 'location',
                'type' => 'text',
            ],
            [
                'name'          => 'Map',
                'id'            => 'map',
                'type'          => 'osm',
                'address_field' => 'location',
            ],
        ],
    ];

    // Add more field groups if you want
    // $meta_boxes[] = ...

    return $meta_boxes;
} );

Each field group has settings and a list of fields, covered below.

Field group settings

Each field group has settings for location or appearance:

Name	Description
id	ID, must be unique. Optional. If it is absent, it will be generated from the title. We recommend specifying the ID explicitly to avoid issues when the title contains non-ASCII characters (e.g. Chinese, Japanese, Korean, or Vietnamese).
title	The field group title. Required.
post_types	Custom post types for the field group. Can be a string or an array of slugs. Must be in lowercase (like the slug). Optional. Default: post.
context	Where the field group is displayed. See below for a list of field group contexts. Optional.
style	Keep the default WordPress field group style (default) or remove the wrapper box and display fields without styling (seamless).
closed	Whether to collapse the field group when the page loads? Optional. Default: false.
priority	Priority within the context where the box is displayed (high or low). Optional. Default: high.
default_hidden	Hide the field group by default (true or false)? Toggle this with the checkbox in screen Help (top right). Optional. Default false.
autosave	Auto save the custom fields' values (like post content and title)? Optional. Default: false.
media_modal	Add custom fields to media modal when viewing/editing an attachment. Works only when post_types is or contains attachment. Optional. Default false.
class	Custom CSS class for the field group wrapper. Optional.

Media modal limitation

Only simple fields such as text, select, radio, and checkbox work in the media modal. Fields that require custom JavaScript do not work.

Contexts

The plugin supports the following contexts (locations) where a field group can appear:

Name	Description
normal	Below the post editor. This is the default value.
advanced	Below the normal section.
side	On the right sidebar.
form_top	Top of the post form, before the post title
after_title	After post title
after_editor	After the post content editor, but before normal section
before_permalink	Before permalink

Block editor

The block editor editor supports only normal and side contexts. Other contexts do not work.

Fields

Add fields to a field group via the fields key. Each field is an array of settings.

Meta Box supports more than 40 field types. They share some common settings but also offer unique settings per field type.

Field types

Know the field type and how it works before adding a field. This helps you choose the right type for your data.

The list below shows all supported field types in alphabetical order with a brief description. The field type key is used for code reference. See the Field types menu for details on how they look and how to use them.

Basic

These basic field types do not require an extra library. They use the WordPress UI.

Type	Key	Description
Checkbox	checkbox	A simple checkbox, usually used for Yes/No question
Checkbox list	checkbox_list	A list of checkboxes where you can select multiple choices
Radio	radio	Radio input where you can select only one choice
Select	select	Select dropdown where you can select one or multiple choice
Text	text	A single-line text input
Textarea	textarea	A paragraph text input

Advanced

These advanced field types need an additional library for the UI.

Type	Key	Description
Background	background	Set background properties
Button	button	A simple button, usually used for JavaScript triggers
Button group	button_group	Select one or multiple choices by enabling button(s) from a group
Color picker	color	Color picker
Custom HTML	custom_html	Output custom HTML content
Date picker	date	Date picker
Datetime picker	datetime	Date and time picker
Hidden	hidden	For storing a default hidden value
Image Select	image_select	Select a choice with images
Key Value	key_value	Add an unlimited group of key-value pairs
Google maps	map	Google Maps
oEmbed	oembed	Input for media from Youtube, Vimeo, and all supported sites by WordPress
Open Street Maps	osm	Open Street Maps
Password	password	For entering a password
Select advanced	select_advanced	Select dropdown with search using select2 library
Slider	slider	jQuery UI slider
Switch	switch	On/off switch with iOS style
Time picker	time	Time picker
WYSIWYG editor	wysiwyg	WordPress editor

These field types are not recommended. Their UI is not as good as other fields.

Type	Key	Description
Autocomplete	autocomplete	Text input that uses an autocomplete library to suggest user input. Not recommended. Use the Select or Select advanced field type instead.
Fieldset text	fieldset_text	Group of text inputs. Not recommended. Use the Group field type instead.
Text list	text_list	Group of text inputs. Similar to Fieldset text, but has a different UI. Not recommended. Use the Group field type instead.

HTML5

warning

These field types use the built-in browser UI without extra libraries. The UI is different across operating systems and browsers. Use with care.

Type	Key	Description
Email	email	For entering an email address with browser validation
Number	number	For entering a number with browser validation
Range	range	A slider for selecting a number
URL	url	An input for URL with browser validation

WordPress

These are field types that help you select a WordPress object.

Type	Key	Description
Post	post	For selecting posts
Sidebar	sidebar	For selecting sidebars
Taxonomy	taxonomy	For selecting taxonomy terms. Does not save term IDs in post meta, but sets post terms.
Taxonomy advanced	taxonomy_advanced	For selecting taxonomy terms and saving term IDs in post meta as a comma-separated string. It does not set post terms.
User	user	For selecting users

Upload

These are field types that help you upload media files.

Type	Key	Description
File	file	Simple file upload with default UI like <input type="file" />. Not recommended. Use File advanced instead.
File advanced	file_advanced	Multiple file uploads with WordPress media popup
File input	file_input	A text input for entering a file URL with the ability to select a file from the Media Library
File upload	file_upload	Multiple file uploads with a drag and drop area
Image	image	Simple image upload with default UI like <input type="file" />. Not recommended. Use Image advanced instead.
Image advanced	image_advanced	Multiple image uploads with WordPress media popup, usually used for a gallery
Image upload	image_upload	Multiple image uploads with a drag and drop area
Single image	single_image	Single image upload with WordPress media popup
Video	video	Multiple video uploads with WordPress media popup

Layout

These are field types that help you organize and improve the UI of the fields.

Type	Key	Description
Divider	divider	Simple horizontal line
Heading	heading	Heading text
Group	group	For creating nesting groups of fields. Requires MB Group extension.
Tab	tab	For organizing fields in tabs. Requires MB Tabs extension.

Field settings

Each field has settings for where and how data is loaded and saved. All fields share common settings. Each field type also has unique settings. Extension settings are explained in each extension docs.

Below is the list of settings with a brief description. The keys are for reference in code.

General

Name	Key	Description
Label	name	Field label. Optional. If empty, the field input is 100% width.
ID	id	Field ID. Required and must be unique. The ID is used as meta_key when saving to the database. Use only numbers, letters, and underscores (and rarely dashes).
Type	type	Field type. Required.
Label description	label_description	Label description, displayed below the field label. Optional.
Input description	desc	Field description, displayed below the field input. Optional.
Default value	std	Default value. Optional.
Placeholder	placeholder	Placeholder text for the input or select box. Optional.
Required	required	Whether the field is required (true or false). Optional. Default false.
Disabled	disabled	Whether the field is disabled (true or false). Optional. Default false.
Read only	readonly	Whether the field is read only (true or false). Optional. Default false.
Multiple	multiple	Does the field have multiple values (like the select field)? Optional. Default false.
Cloneable	clone	Is the field clonable (repeatable)? true or false. Optional. Default false.
Sortable	sort_clone	Ability to drag-and-drop reorder clones (true or false). Optional. Default false.
Clone default value	clone_default	Clone the default value of fields? true or false (default).
Clone as multiple	clone_as_multiple	Whether to store clone values in multiple rows in the database? Optional. Default false.
Max number of clones	max_clone	Maximum number of clones. Optional. Default 0 (unlimited).
Min number of clones	min_clone	Minimum number of clones. Optional. Default 0.
Add more text	add_button	The text for Add more clone button. Optional. Default "+ Add more".

Advanced

Name	Key	Description
Before	before	Custom HTML output before the field HTML.
After	after	Custom HTML output after the field HTML.
Custom CSS class	class	Custom CSS class, in case you want to customize the field. Optional.
Custom sanitize callback	sanitize_callback	Custom PHP callback for sanitizing field value before saving to the database. Set to none to bypass sanitization. See more details.
Save field value	save_field	Whether to save field value. Optional. Default true. This option does not work in the block editor (Gutenberg).
Hide from block bindings?	hide_from_block_bindings	Hide this field from the block editor bindings UI. Optional. Default false. See more details.
Custom HTML5 attributes	attributes	Custom attributes for inputs. See more details.
Validation	validation	Validation rules for fields. Optional. See more details.
Custom settings	N/A	Custom field settings, useful when you want to add your settings to fields.

Field ID prefix

You can add a prefix to field IDs to prevent using the same ID with other scripts. If you want to hide the fields in the default WordPress Custom Fields meta box, use underscore (_) as the prefix.

Field-specific settings

In addition to common settings, each field type has its own settings. See the left menu for details on each field type.

Code examples

To save time, we have prepared code examples in the Meta Box Code Snippet Library.

Shorthand syntax

For text field type, you can omit the type settings, like this:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
    $meta_boxes[] = [
        'title'      => 'Event details',
        'post_types' => 'event',
        'fields'     => [
            [
                'name' => 'Date and time',
                'id'   => 'datetime',
                'type' => 'datetime',
            ],
            [
                'name' => 'Location',
                'id'   => 'location',
            ],
            [
                'name'          => 'Map',
                'id'            => 'map',
                'type'          => 'osm',
                'address_field' => 'location',
            ],
        ],
    ];

    return $meta_boxes;
} );

And if the id of the field can be auto-generated from the field name, you can omit it and define the field as a simple string:

add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
    $meta_boxes[] = [
        'title'      => 'Event details',
        'post_types' => 'event',
        'fields'     => [
            [
                'name' => 'Date and time',
                'id'   => 'datetime',
                'type' => 'datetime',
            ],
            'Location',
            [
                'name'          => 'Map',
                'id'            => 'map',
                'type'          => 'osm',
                'address_field' => 'location',
            ],
        ],
    ];

    return $meta_boxes;
} );

Video tutorial

This video shows all field types and field settings:

FAQ

Why does not my default value work?

The std value works only if the field group has not been saved before. This applies to all fields in the group, not just the field with std. If any field has a value, std does not work for other fields, even new ones you add.

Examples:

When you create a new post, no fields have values. std works for all fields.

When you edit an existing post with a field group, some fields may have values. Then std does not work for all fields. If you add a new field to the field group, std does not work for that field, even if it has no value. The field group was saved before.

# Link to this question

Why does not my context work?

The context may not work if you dragged and dropped field groups to reorder them. WordPress saves the position and uses it instead of the context value. The order is saved in user meta meta-box-order_{screen id}:

To fix this, delete the user meta from the database. The context will work again.

# Link to this question