Taxonomy

Improve this page

Overview

The taxonomy field allows you to select one or multiple taxonomy terms. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.

If the taxonomy is hierarchical, you are able to display the field as a select or checkbox tree, e.g. show childen terms when parent term is selected.

Screenshots

Beautiful select with select2 library (default):

Checkbox list:

Checkbox tree:

Radio list:

Radio list inline:

Select tree:

Settings

Besides the common settings, this field has the following specific settings:

Name	Description
taxonomy	Taxonomy slug(s). Can be string for single taxonomy or array for taxonomies. Required.
query_args	Query arguments for getting taxonomy terms. Uses same arguments as get_terms(). Optional.
placeholder	The placeholder for the select box. Default is “Select a {taxonomy label}”. Applied only when the field_type is a select field.
add_new	Allow users to create a new term when submitting the post (true or false). Added in v4.18.0.
field_type	How the terms are displayed? See below.

This field inherits the look and field (and settings) from other fields, depending on the field_type, which accepts the following value:

Field type	Description	Settings inherited from
select	Simple select dropdown.	select
select_advanced	Beautiful select dropdown using the select2 library. This is the default value.	select_advanced
select_tree	Hierachical list of select boxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy type is hierarchical (like pages).	select
checkbox_list	Flatten list of checkboxes which allows to select multiple items.	checkbox_list
checkbox_tree	Hierachical list of checkboxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy type is hierarchical (like pages).	checkbox_list
radio_list	Flatten list of radio boxes which allows to select only 1 item.	radio

Note that for select_tree, checkbox_list, checkbox_tree, the multiple setting is always set to true.

Sample code

This code shows pages in select2 dropdown:

array(
    'name'       => 'Taxonomy',
    'id'         => 'taxonomy',
    'type'       => 'taxonomy',

    // Taxonomy slug.
    'taxonomy'   => 'category',

    // How to show taxonomy.
    'field_type' => 'select_advanced',
),

The code below shows pages in a checkbox tree format:

array(
    'name'       => 'Taxonomy',
    'id'         => 'taxonomy',
    'type'       => 'taxonomy',

    // Taxonomy slug.
    'taxonomy'   => 'category',

    // How to show taxonomy.
    'field_type' => 'checkbox_tree',
),

Data

This field does not save any value in the database. Instead of that, it sets the taxonomy terms for the current being edited post. In short, it behaves exactly like the “Category” and “Tags” meta boxes.

The purpose of this field is to replace the default WordPress meta box for taxonomy and offer more options to control how it displays.

For this reason, if you have 2 taxonomy field, and select different values for them, after saving, they still show the same value.

If you prefer saving data, check out taxonomy advanced.

Template usage

Getting value of this field can be done via the helper function:

$terms = rwmb_meta( $field_id );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo '<p>', $term->name, '</p>';
    }
}

If the field is neither cloneable or multiple, e.g. it has single value, then the rwmb_meta() function returns the single term object:

$term = rwmb_meta( $field_id );
echo '<p>', $term->name, '</p>';

The code above shows the term name only. If you want to show term link, use this code:

$term = rwmb_meta( 'pub_type_field' );
printf( '<a href="%s">%s</a>', get_term_link( $term ), $term->name );

If you just want to output selected terms in an unordered list, use this code:

rwmb_the_value( $field_id );

Read more about rwmb_meta() and rwmb_the_value().