CMB2 is a metabox, custom fields, and forms library for WordPress that will blow your mind.
CMB2 is a developer’s toolkit for building metaboxes, custom fields, and forms for WordPress that will blow your mind. Easily manage meta for posts, terms, users, comments, or create custom option pages.
CMB2 is a complete rewrite of Custom Metaboxes and Fields for WordPress. To get started, please follow the examples in the included example-functions.php
file and have a look at the basic usage instructions.
You can see a list of available field types here.
Development occurs on Github, and all contributions welcome. Please read the CONTRIBUTING doc for more details.
A complete list of all our awesome contributors found here: github.com/CMB2/CMB2/graphs/contributors
If you are looking to provide language translation files, Please do so via WordPress Plugin Translations.
Custom Field Types
custom_attached_posts
, for attaching posts to a page.post_search_ajax
Attach posts to each other. Same approach as CMB2 Attached Posts Field but with Ajax request, multiple/single option, and different UI.user_search_text
adds a user-search dialog for searching/attaching other User IDs.CMB2 Field Type: Google Maps from mustardBees: Custom field type for Google Maps.
The
pw_map
field stores the latitude/longitude values which you can then use to display a map in your theme.
CMB2 Field Type: Leaflet Maps from villeristi: Custom field type for Leaflet Maps.
CMB2 Field Type: Select2 from mustardBees: Custom field types which use the Select2 script:
- The
pw_select field
acts much like the default select field. However, it adds typeahead-style search allowing you to quickly make a selection from a large list- The
pw_multiselect
field allows you to select multiple values with typeahead-style search. The values can be dragged and dropped to reorder
CMB Field Type: Slider from mattkrupnik: Adds a jQuery UI Slider field.
'apply_term' => false
) to disable and save the term ids as data instead (like for options pages, etc).select
field. However, it adds the support for optgroup
and saving of values with multiple
attribute.Other Helpful Resources
If installing the plugin from wordpress.org:
/CMB2
directory to the /wp-content/plugins/
directory.example-functions.php
into to your theme or plugin’s directory.If including the library in your plugin or theme:
example-functions.php
into a folder above the CMB directory OR copy the entirety of its contents to your theme’s functions.php
file.FAQ’s usually end up in the github wiki.
object_id
and mb_object_type
and in do_scripts
– Allows overriding by plugins/libs. (Added to support the new CMB2 WooCommerce HPOS Orders extension)cmb2_init_hooks
hook when hookup is called.DateTime
field values (text_datetime_timestamp_timezone
field type only). (#1510)https
. Props @paulschreiber (#1413).shiftRows
functionality to be simpler, and fix issues with JS initialization. Fixes #1426 and #1431.Required parameter $i follows optional parameter $args...
. Props @carloswph (#1417).cmb2_tab_group_tabs
filter for adding arbitrary menu page urls to the cmb2 tabs, and move tab markup output to separate method, CMB2_Options_Hookup::options_page_tab_nav_output()
. Fixes #1407.get_allowed_mime_types()
, which makes SVGs more reliable when using the Safe SVG plugin. Fixes #1223.func_get_args()
. Fixes #1389.5
instead of the default 10
, causing some back-compatibility issues. Fixes #1410.enqueue wp-color-picker
is enqueued for color fields. Props @rubengc (#1339).'file_list'
buttons. Props @pgroot91 (#1347).wysiwyg
field type not working in a group, by ensuring scripts properly enqueued. Props @yoren (#1361).$object_id
doc block types in helper-functions.php. Fixes #1365.PHP Deprecated: Required parameter $field_id follows optional parameter $type
, due to changes in PHP 8.0. Fixes #1396.deprecated_param
method in PHP 7.4. Props @jonathanstegall (#1400).'column' => array( 'disable_sortable' => true )
. Props @RubenMartins (#1281).'taxonomy_select_hierarchical'
. Fixes #751text
, textarea
and wysiwyg
character counter options. For now, this feature is not available to wysiwyg
field types within repeatable groups. Props @gyrus (#1276). 'char_counter'
– Defaults to false, no counter. Set to true, or words
to count words instead of characters.'char_max'
– integer. When defined, counter shows remaining characters/words.'char_max_enforce'
– boolean, default: false. Currently only applied (as maxlength attribute) to text
and textarea
fields which use 'characters'
for counter.'words_left_text'
– Default: “Words left”'words_text'
– Default: “Words”'characters_left_text'
– Default: “Characters left”'characters_text'
– Default: “Characters”'characters_truncated_text'
– Default: “Your text may be truncated.”register_rest_field_cb
, which when used allows overriding the way CMB2 handles the register_rest_field
callbacks, and defining your own REST prefix for your fields. See this PR comment for more context.CMB2_hookup
to CMB2_Hookup
. Classes are case-insensitive, so this is a backwards-compatible change. Props @szepeviktor (#1330, #1328)."cmb2_display_class_{$fieldtype}"
filter and 'display_class'
field parameter to allow specifying the class to use to display the field (in admin columns, etc).CMB2_Types::_id()
to allow not appending the iterator attribute if a repeatable field.CMB2_Utils::concat_attrs()
test for nested arrays as data attributes.cmb2_add_row
triggered event.CMB2_Field::get_rest_value()
to get values for fields in the post REST API endpoints (#1284).file
and text_datetime_timestamp_timezone
field types, the supporting field data was not provided (e.g. the file id for file
field, and the utc
value for the text_datetime_timestamp_timezone
field). Fixes https://wordpress.org/support/topic/cmb2-rest-api-image-file-field-as-an-object/.taxonomy_select_hierarchical
now saves to the correct location, the term relationships table. Props @latheva (#1307)./wp/v2/{post_type}
) would show all boxes for all custom post types even though not registered to the post-type. Props @Mte90 (#1238).function_exists( 'add_action' )
check to bootstrap file to ensure compatibility with composer usage. Props @salcode (#1271, #1270)get_user_locale()
in admin area instead of get_locale()
. Fixes #1267.CMB2::is_box_type()
now also checks for taxonomies if box is registered to “term” object type. This should fix some issues where CMB2 term meta was not showing up in REST API requests to the term endpoints.rest_value_cb
registering of filter. Props @lipemat (#1212).CMB2_Utils::filter_empty
from CMB2::save_group_field
is always an array. (#1026).postbox
divs to ensure compatibility with scripts which expect ids there. Props @amans2k (#1108).CMB2_Option
properties accessible. (#1052)'cmb2_before_field_row'
, "cmb2_before_{$field_type}_field_row"
, "cmb2_after_{$field_type}_field_row"
, 'cmb2_after_field_row'
. Props @rubengc (#953).'cmb2_field_defaults'
, 'cmb2_field_arguments_raw'
, 'cmb2_field_arguments'
. Props @jrfnl (#588).core/editor
object does not exist (is undefined), causing incompatibility issues with Yoast and likely others. Fixes #1197sv_SE
translation. Props @edvind (#370).'mb_callback_args'
CMB2 box property which allows defining the $callback_args
passed into add_meta_box()
. This allows using defining the new Gutenberg/block-editor compatibility parameters. Fixes #1191cmb_init_pickers
and cmb_init_code_editors
Javascript events for allowing just-in-time configuration for pickers/editors.CMB2_Field::get_rest_value()
method for sending value through several filters ('cmb2_get_rest_value'
, "cmb2_get_rest_value_{$field_type}"
, "cmb2_get_rest_value_for_{$field_id}"
) before sending to REST request.call_user_func
. Props @manzoorwanijk (#1177).wysiwyg
fields’ visual tab wouldn’t save content on Gutenberg/block-editor posts. Props @staurand (#1190 fixes #1156).remove_default
wouldn’t actually remove the default taxonomy metabox when box registration used an alternate box context. Props @lipemat (#1147).textarea_code
fields registered on the page. Fixes #1110.wysiwyg
field values to string “false” when boolean false. Fixes #1138 (again!).'tab_group'
CMB2 box property. This snippet demonstrates how to create a top-level menu options page with multiple submenu pages, each with the tabbed navigation. To specify a different tab title than the options-page title, set the 'tab_title'
CMB2 box property. See #301, #627.zh-CN
translation. Props @uicestone (#1089).nl_NL
translation. Props @tammohaannl (#1101)."cmb2_should_autoload_{$options_key}"
) or via a box parameter for 'options-page'
box registrations ('autoload' => false,
). (#1093)'textarea_code'
field type now uses CodeMirror that is used by WordPress (#1096). A field can opt-out to return to the previous behavior by specifying an 'options'
parameter:
‘options’ => array( ‘disable_codemirror’ => true )
As with the other javascript-enabled fields, the code-editor defaults can be overridden via a data-codeeditor
attribute. E.g:
`php
‘attributes’ => array(
‘data-codeeditor’ => json_encode( array(
‘codemirror’ => array(
‘mode’ => ‘css’,
),
) ),
),
`
resetBoxes
/resetBox
Javascript methods for resetting CMB2 box forms.CMB2_Boxes
methods for filtering instances of CMB2
, CMB2_Boxes::get_by( $property, $optional_compare )
and CMB2_Boxes::filter_by( $property, $to_ignore = null )
.'taxonomy_*'
fields when used for term fields/meta. Save the value to term-meta.Fatal error: Declaration of CMB2_Type_Colorpicker::render() must be compatible with CMB2_Type_Text::render($args = Array)...
). (#1070, #1074, #1075).jw-cmb2-rgba-picker-js
script (and enqueue our wp-color-picker-alpha
) if it is actually found.'alpha'
option to the field options array. Thank you to JayWood for his work on his custom field type.'before_group'
parameter.'render_row_cb'
param for group fields. Fixes #1041.CMB2::get_field()
).CMB2_Base::unset_param_callback_cache()
).'message_cb'
box property, which allows defining a custom callback for adding options-save messages on options-page
boxes.'file'
field type ID is removed from the database if the 'file'
field type’s value is empty (Support thread).user_can_richedit()
is false (“Disable the visual editor when writing” user option is checked, or various unsupported browsers). See #1031.F j, Y
) would not properly translate into jQuery UI date formats. Support thread'select_all_button' => false
was not working for 'taxonomy_multicheck'
field type (#1005)."cmb2_init_hookup_{$cmb_id}"
hook. Allows plugins to unhook/rehook/etc.CMB2_Utils::normalize_if_numeric()
to address problems when using floats as select/radio values. Fixes #869. See #1013.CMB2_Options_Hookup::$option_key
property.options-general.php
), and if the errors are not disabled via the 'disable_settings_errors'
box property.'taxonomy_radio_hierarchical'
, and 'taxonomy_multicheck_hierarchical'
, for displaying taxonomy options in a hierarchical layout. Props to eriktelepovsky for the working code. (#640)cmb2_group_wrap_attributes
filter.'query_args'
, which can be used by the 'taxonomy_*'
fields. Provides ability to override the arguments passed to get_terms()
.cmb2_can_save
filter now passes the CMB2 object as the 2nd parameter. Props @Arno33 (#994).CMB2_Types::file()
method.CMB2_Field:options()
method apart to allow re-setting options from field params. Related: reaktivstudios/cmb2-flexible-content/pull/8.CMB2:box_types()
method for getting the array of registered 'object_types'
for a box. Ensures the return is an array.CMB2::show_form()
CMB2::render_form_open()
CMB2::render_form_close()
CMB2::render_group_row()
CMB2::render_hidden_fields()
CMB2::save_fields()
CMB2::process_fields()
CMB2::process_field()
CMB2::pre_process()
CMB2::after_save()
CMB2::add_fields()
file
/file_list
fields to properly show a preview for SVG images. Fixes #874..button-secondary
class instead of the .button
class. This alleviates some front-end issues for themes which target the .button
class. This is a backwards-compatibility break. If your theme or plugin targets the .button
class within CMB2, you will need to update to use .button-secondary
.CMB2_Option
methods are called when the option value is empty, as well as additional unit tests for the CMB2_Option
class. Props @anhskohbo (#993).|
or /
from breaking file fields. Props @lipemat (#1003).jQuery.fn.attr('value', val) no longer sets properties
warning.'taxonomy_*'
fields to return stored terms for non-post objects.CMB2::get_sanitized_values()
to return the sanitized 'taxonomy_*'
field values. Also added "cmb2_return_taxonomy_values_{$cmb_id}"
filter to modify if 'taxonomy_*'
field values are returned. Fixes #538.Allow outputting CMB2 boxes/fields in additional locations in the post-editor.
The new locations are:form_top
, before_permalink
, after_title
, and after_editor
These would be defined by setting the context
property for your box:
`php
$cmb_demo = new_cmb2_box( array(
…
‘context’ => ‘before_permalink’,
) );
`
If it is preferred that the fields are output without the metabox, then omit the 'title'
property from the metabox registration array, and instead add 'remove_box_wrap' => true,
.
'render_class'
, allowing you to override the default 'CMB2_Type_Base'
class that is used when rendering the field. This provides interesting object-oriented ways to override default CMB2 behavior by subclassing the default class and overriding methods. The render class can also be overridden with the "cmb2_render_class_{$fieldtype}"
filter, which is passed the default render class name as well as the CMB2_Types
object, but this should be used sparingly, and within the context of your project’s boxes/fields or you could break other plugins’/themes’ CMB2 fields.file
/file_list
fields javascript APIs, including using undersore templates.file_list
field type.cmb2_footer_enqueue
, which occurs after CMB2 enqueues its assets.CMB2_Utils
methods, get_available_image_sizes()
and get_named_size()
. Props @Cai333.'quicktags'
param is set to false. Props @timburden (#797, #796).file_list
item could occasionally remove the field row. (#828).file
/file_list
field preview images work with named sizes. Props @Cai333 (#848, #844).CMB2_Utils::get_file_ext()
.title
field type has no name value, then only output a span element (instead of a header element).label[for=""]
selector. Fixed Syntax error, unrecognized expression
. Props @anhskohbo (#789).ReferenceError: tinyMCE is not defined
javascript errors (happening when trying to remove a repeatable field/group). Fixes #790, and #730.'show_in_rest'
examples in example-functions.php
. Any REST API boxes/fields must use the 'cmb2_init'
hook (as opposed to the 'cmb2_admin_init'
hook).'save_field'
boolean field parameter for disabling the saving of a field. Useful if you want to display the value of another field, or use a disabled/read-only field. Props @jamesgol (#674, #346, #500).CMB2_Field::save_field_from_data()
and CMB2_Field::save_field()
. Props @jamesgol (#675).'file'
and ‘file_list'
fields). 'cmb_media_modal_init'
, 'cmb_media_modal_open'
, and 'cmb_media_modal_select'
.'remove_default'
which allows disabling the default taxonomy metabox. Props @c3mdigital (#593).'row_classes'
to just 'classes'
, to mirror the metabox 'classes'
property. Also now accepts a 'classes_cb'
parameter for specifying a callback which returns a string or array. The callback will receive $field_args
as the first argument, and the CMB2_Field $field
object as the second argument. ('row_classes'
will continue to work, but is deprecated)'cmb2_group_wrap_attributes'
filter to modifying the group wrap div’s attributes. Filter gets passed an array of attributes and expects the return to be an array. Props jrfnl (#582).$wp_version
global. Props ramiy (#731).'*_cb'
parameters. E.g.php
...
'show_on_cb' => function( $cmb ) { return has_tag( 'cats', $cmb->object_id ); },
...
ABSPATH
) and theme rooth path (get_theme_root()
). Props @rianbotha (#677, #676).'cmb2_remove_row'
Javascript callback for non-group row removal. Fixes #729).'column' => true,
. If you want to dictate what position the column is, use 'column' => array( 'position' => 2 ),
. If you want to dictate the column title (instead of using the field 'name'
value), use 'column' => array( 'name' => 'My Column' ),
. If you need to specify the column display callback, set the 'display_cb'
parameter to a callback function. Columns work for post (all post-types), comment, user, and term object types.'cmb2_meta_box_url'
filter (thought it will continue to work as expected). (#27, #118, #432, related wiki item)classes
and classes_cb
CMB2 box params which allows you to add additional classes to the cmb-wrap. The classes
parameter can take a string or array, and the classes_cb
takes a callback which returns a string or array. The callback will receive $cmb
as an argument. These classes are also passed through a new filter, 'cmb2_wrap_classes'
, which receives the array of classes as the first argument, and the CMB2 object as the second. Reported/requested in #364.'title'
field type accept extra arguments. Props @vladolaru, @pixelgrade (#656).cmb2_get_oembed()
function to NOT return the “remove” link, as it’s intended for outputting the oembed only. This is a backwards-compatibility concern. If you were depending on the “remove” link, use cmb2_ajax()->get_oembed( $args )
instead.cmb2_do_oembed()
‘, which is hooked to 'cmb2_do_oembed'
, so you can use do_action( 'cmb2_do_oembed', $args )
in your themes without function_exists()
checks.CMB2:set_prop( $property, $value )
, for setting a CMB2 metabox object property.CMB2_Field
object instances will now have a cmb_id
property and a get_cmb
method to enable access to the field’s CMB2
parent object’s instance, in places like field callbacks and filters (e.g. $cmb = $field->get_cmb();
).data-fieldtype
attribute to the field rows for simpler identification in Javascript.CMB2_Types
to it’s own class so that each field type can handle it’s own field display, and added the infrastructure to maintainn back-compatibility.CMB2_Utils
methods, notempty()
and filter_empty()
, both of which consider null
, ''
and false
as empty, but allow 0
(for saving 0
as a field value).CMB2_Utils
public methods, get_url_from_dir()
, get_file_ext()
, get_file_name_from_path()
, and wp_at_least()
.cmb_pre_init
Javascript event to allow overriding CMB2 defaults via JS.CMB2_Field::get_default()
method, and 'default_cb'
field parameter. Using the 'default'
field parameter with a callback will be deprecated in the next few releases. (#572).CMB2_Field::row_classes()
for group field rows. Also, update CSS to use the “cmb-type-group” classname instead of “cmb-repeat-group-wrap”.'text'
and 'text_cb'
field parameters for overriding CMB2 text strings instead of using the 'options'
array. (#630)CMB2::$updated
parameter (which contains field ids for all fields updated during a save) now also correctly adds group field ids to the array.yourprefix_register_taxonomy_metabox
function in example-functions.php.'cmb2_save_field'
and "cmb2_save_field_{$field_id}"
. Props wpsmith (#475).CMB2::show_form()
is now composed of 3 smaller methods, CMB2::render_form_open()
, CMB2::render_field()
, CMB2::render_form_close()
(#506)..gitattributes
file for excluding development resources when using Composer. Props @benoitchantre (#575, #53).'taxonomy_select'
field type where a term which evaluated falsey would not be displayed properly. Props adamcapriola (#477).