Fields

WP Backstage can render several custom fields, all of which are available to all components and can be managed using the same normalized API. The field type will determine the UI that is rendered, the content in the column (if the component is tabled), and the sanitization that is used.

Arguments

type string ― The field's type. This will determine how the field is rendered in the form, how the value is displayed in the column, and how the value is sanitized.
name string ― The field's name. This will be used as the the field's identifier, key and input name.
label string ― The field's label.
description string ― The field's description.
help string ― The field's help tab content.
has_column bool ― Whether the field has a column or not. This will only be used in components with tabled layouts, such as post types, taxonomies, and users.
is_sortable bool ― Whether the field's column is sortable or not. This will only be used in components with tabled layouts, such as post types, taxonomies, and users.
is_filterable bool ― Whether the field renders a table filter or not. This will only be used in components with tabled layouts, such as post types, taxonomies, and users. This only applies to field types of "select", "radio", "select_posts", and "select_users".
options array ― An array of options. This only applies to enumerated field types such as "select", "radio", and "checkbox_set".
- value string ― The option's value.
- label string ― The option's label.
- disabled bool ― Whether the option is disabled or not.
show_in_rest bool ― Allows for the fields value to be integrated into the REST API for supported components like post type, taxonomy, and user.
input_attrs array ― An array of "name: string => value: mixed" pairs that will be applied to the form input itself.
args array ― An array of "key: string => value: mixed" pairs that will be used as the extra arguments for the field that control more advanced functionality. The accepted arguments are different for each field type.

Text

Write single line text.

array(
    'type'         => 'text',
    'name'         => 'wp_backstage_text_field',
    'label'        => __( 'Text', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'is_sortable'  => true,
    'is_sortable'  => true,
    'show_in_rest' => true,
)

Text Area

Write multi-line text.

array(
    'type'         => 'textarea',
    'name'         => 'wp_backstage_textarea_field',
    'label'        => __( 'Textarea', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'input_attrs'  => array(
        'maxlength' => 240,
    ),
)

URL

Set a valid URL.

array(
    'type'         => 'url',
    'name'         => 'wp_backstage_url_field',
    'label'        => __( 'URL', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
)

Email

Set a valid email address.

array(
    'type'         => 'email',
    'name'         => 'wp_backstage_email_field',
    'label'        => __( 'Email', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
)

Telephone

Set a telephone number or other alpha-numeric value.

array(
    'type'         => 'tel',
    'name'         => 'wp_backstage_phone_field',
    'label'        => __( 'Phone', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
)

Number

Set a numeric value with minimum, maxiumum and step constrictions.

array(
    'type'         => 'number',
    'name'         => 'wp_backstage_number_field',
    'label'        => __( 'Number', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'is_sortable'  => true,
    'show_in_rest' => true,
    'input_attrs'  => array(
        'min'  => 0,
        'max'  => 100,
        'step' => 1,
    ),
),

Checkbox

Set a boolean value.

array(
    'type'         => 'checkbox',
    'name'         => 'wp_backstage_checkbox_field',
    'label'        => __( 'Checkbox', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'is_sortable'  => true,
    'show_in_rest' => true,
)

Select

Select a single value from a group of options.

array(
    'type'          => 'select',
    'name'          => 'wp_backstage_select_field',
    'label'         => __( 'Select', 'wp_backstage_examples' ),
    'description'   => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'          => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'    => true,
    'is_sortable'   => true,
    'is_filterable' => true,
    'show_in_rest'  => true,
    'options'       => array(
        array(
            'value' => '',
            'label' => __( '― Select an Option ―', 'wp_backstage_examples' ),
        ),
        array(
            'value' => 'option_1',
            'label' => __( 'Option 1', 'wp_backstage_examples' ),
        ),
        array(
            'value' => 'option_2',
            'label' => __( 'Option 2', 'wp_backstage_examples' ),
        ),
        array(
            'value'    => 'option_3',
            'label'    => __( 'Option 3', 'wp_backstage_examples' ),
            'disabled' => true,
        ),
        array(
            'value' => 'option_4',
            'label' => __( 'Option 4', 'wp_backstage_examples' ),
        ),
    ),
)

Radio

Select a single value from a group of options.

array(
    'type'          => 'radio',
    'name'          => 'wp_backstage_radio_field',
    'label'         => __( 'Radio', 'wp_backstage_examples' ),
    'description'   => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'          => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'    => true,
    'is_sortable'   => true,
    'is_filterable' => true,
    'show_in_rest'  => true,
    'options'       => array(
        array(
            'value' => 'option_1',
            'label' => __( 'Option 1', 'wp_backstage_examples' ),
        ),
        array(
            'value' => 'option_2',
            'label' => __( 'Option 2', 'wp_backstage_examples' ),
        ),
        array(
            'value'    => 'option_3',
            'label'    => __( 'Option 3', 'wp_backstage_examples' ),
            'disabled' => true,
        ),
        array(
            'value' => 'option_4',
            'label' => __( 'Option 4', 'wp_backstage_examples' ),
        ),
    ),
)

Checkbox Set

Select multiple values from a group of options.

array(
    'type'         => 'checkbox_set',
    'name'         => 'wp_backstage_checkbox_set_field',
    'label'        => __( 'Checkbox Set', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'options'      => array(
        array(
            'value' => 'option_1',
            'label' => __( 'Option 1', 'wp_backstage_examples' ),
        ),
        array(
            'value' => 'option_2',
            'label' => __( 'Option 2', 'wp_backstage_examples' ),
        ),
        array(
            'value'    => 'option_3',
            'label'    => __( 'Option 3', 'wp_backstage_examples' ),
            'disabled' => true,
        ),
        array(
            'value' => 'option_4',
            'label' => __( 'Option 4', 'wp_backstage_examples' ),
        ),
    ),
)

Media

Select attachments from all uploaded media, and upload new ones.

array(
    'type'         => 'media',
    'name'         => 'wp_backstage_gallery_field',
    'label'        => __( 'Gallery', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'args'         => array(
        'type'     => 'image',
        'multiple' => true,
        'attach'   => true,
    ),
)

Media Arguments

type string ― The mime type that will be used to filter the media modal's results and enforce the selection of only those attachments with that mime type. The mime type base can also be used alone, ie: "image", "video", "audio", "application", etc. Note that this must be one of of the allowed mime types in WordPress.
multiple bool ― Whether selection of multiple attachments is allowed or not.
attach bool ― Whether the attachment is actually attached relationally to the post or not. Note that this is only relevant on post type components and the attachment will only attach to the post if the attachment does not already have a relationship with another post. Either way, the value will be stored in the custom meta field.

Date

Set a formatted date with a date picker.

array(
    'type'         => 'date',
    'name'         => 'wp_backstage_datepicker_field',
    'label'        => __( 'Date', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'is_sortable'  => true,
    'show_in_rest' => true,
    'args'         => array(
        'format' => 'yy-mm-dd',
    ),
)

Date Arguments

format string ― The php date format that the value is saved as.

Time

Set a formatted time with a time picker.

array(
    'type'         => 'time',
    'name'         => 'wp_backstage_time_field',
    'label'        => __( 'Time', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'is_sortable'  => true,
    'show_in_rest' => true,
)

Color

Set a formatted color with a color picker.

array(
    'type'         => 'color',
    'name'         => 'wp_backstage_color_field',
    'label'        => __( 'Color', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'args'         => array(
        'palettes' => array( '#ffffff', '#000000', '#67b0ff', '#ff9900' ),
        'mode'     => 'hsv',
    ),
)

Color Arguments

palettes bool | array ― Whether the predefined palettes should be used or not. Set custom palettes by providing an array of color strings.
mode hsv | hsl ― The color picker's mode. Setting "hsl" will render a photoshop-like experience, while "hsv" will render the default WordPress experience.

Code

Write code of multiple languages with syntax highlighting and linting.

array(
    'type'         => 'code',
    'name'         => 'wp_backstage_html_field',
    'label'        => __( 'Code (CSS)', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'args'         => array(
        'mime' => 'text/html',
    ),
)

Code Arguments

mime string ― The mime type that the code editor should use for syntax highlighting and linting. Common mime types include "text/html", "text/css", "text/javascript", etc.

Editor

Write rich content with a WordPress TinyMCE WYSIWYG Editor.

array(
    'type'         => 'editor',
    'name'         => 'wp_backstage_editor_field',
    'label'        => __( 'Editor', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
    'args'         => array(
        'media_buttons' => true,
        'format_select' => true,
        'kitchen_sink'  => true,
    ),
)

Editor Arguments

format_select bool ― Whether the editor has a format selector (h1-h6, paragraph, etc.) or not.
media_buttons bool ― Whether the editor has the "Add Media" buttons or not. This adds for attachments to be added into the editor via the WordPress media modal.
kitchen_sink bool ― Whether the editor has the second row of advanced controls or not.

Address

Set a formatted address with address lines, city, region, zip, and country.

array(
    'type'         => 'address',
    'name'         => 'wp_backstage_address_field',
    'label'        => __( 'Address', 'wp_backstage_examples' ),
    'description'  => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'         => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'   => true,
    'show_in_rest' => true,
)

Select Posts

Select a post of any post type.

array(
    'type'          => 'select_posts',
    'name'          => 'wp_backstage_select_post_field',
    'label'         => __( 'Post', 'wp_backstage_examples' ),
    'description'   => __( 'This is the description for this field.', 'wp_backstage_examples' ),
    'help'          => __( 'This is the help tab content for this field.', 'wp_backstage_examples' ),
    'has_column'    => true,
    'is_filterable' => true,
    'show_in_rest'  => true,
    'args'          => array(
        'option_none_label' => __( 'Select a post', 'wp_backstage_examples' ),
        'query'             => array(
            'post_type'   => 'post',
            'post_status' => array( 'publish', 'draft', 'scheduled', 'private', 'pending', 'private', 'trash' ),
        ),
    ),
)

Select Posts Arguments

query array ― An array of get_posts() arguments.
option_none_label bool ― The label for the "empty" option.

Select Users