Fields

WP Custom Fields supports a wide variety of fields which each have their unique properties. These are described on this page. Some fields store their data in an array of data, which is also elaborated under each field.

If you want to see how this looks like in actual code, head to the examples on the pages for Adding Options Pages, Adding Custom Metaboxes or Adding Customizer Settings.

 

Customizer Fields

Customizer fields have a slightly different approach. You can find their configuration under Adding Customizer Settings.

 

Section Properties

Fields are placed in sections, which may reflect a tab in any location or a panel in the Customizer. A section has the following properties:

Property	Type	Description
description	string	The description for this section
fields	array	required The array of fields belonging to this section
icon	string	The material icon displayed in the tab of this section, for example,'favorite_border'
id	string	required The id of this section
tabs	boolean	To display the tab of a field. With only having one section, this can be set to false to hide the tabs. Defaults to true.
title	string	The title of this section
display_title	boolean	Display the section title above fields. defaults to true

 

Common Field Properties

The following properties are common for each field. However, not all of these apply to fields added within the customizer.

Property	Type	Description
class	string	An optional class for the field.
columns	string	The column width of this field. Accepts full, three-fourth, two-third, half, third, fourth.
default	string or array	The default values for this field.
description	string	The description for this field
dependency	string	The dependencies for this field, use the format ['source' => 'id_of_dependent_field', 'equation' => '=', 'value' => 'required value']. This hides the field unless the source field (defined with the field id from this field under source) matches equation and value. Equation supports both '=' as '!='. Dependencies work with input, checkbox and select field types as a source field, and also work in repeatable field groups (then they will target fields in the same group)
id	string	required The id of this field
name	string	Optional name for this field. By default, the name is similar to the id.
placeholder	string	Optional placeholder for this field. Supported by many field types such as input, select and textarea.
title	string	The title of this field
type	string	required The field type. Supports 'background', 'border', 'boxshadow', 'button', 'checkbox', 'code',, 'colorpicker', 'dimensions', 'divider', 'editor', 'export', 'gallery', 'heading', 'icons', 'input', 'location', 'media', 'radio', 'repeatable', 'select', 'slider', 'textarea', 'typography'

 

CSS Styling from Field Properties

Some of the fields are also able to convert their data to css-styling on the front-end. Fields which support this feature are background, boxshadow, border, colorpicker, dimensions, media and typography.

This can be achieved to the adding the following property to a field:

Property	Type	Description
selector	string or array	The css selector to output styling to, for example '.site-header'

The dimensions and colorpicker field also support custom css properties. The value of the field is then set to that given property. In that case, the selector property should be formatted as an array in the following manner: ['selector' => '.css-selector', 'property' => 'background-color'].

  #Fields

Background

The background fields displays an upload field for a custom background image, a colorpicker and some select fields to choose the repeat, attachment, size and position of your background field.

Unique Properties

Key	Type	Description
labels	array	Optional custom labels for our WP Media Modal. Should be in the following format: ['add' => __('Label for the addition button'), 'button' => __('Label for the Media Modal insert button'), 'title' => __('Title on top of the Media Modal')]
properties	array	Custom properties for our box-shadow fields, following the properties as defined in the configurations for the background field (see src/fields/background.php). Allows for translations or adjustment of properties.

Output of a Background Field

The background field stores its data in the following keys:

Key	Description
color	The background colour value
upload	The attachment id for the uploaded background
repeat	The repeat value for the background, such as 'no-repeat'
attachment	The attachment of the background, such as 'fixed'
size	The size of the background, such as 'cover'
position	The position of the background, such as 'center top'

 

Border

The border field displays a selection of fields in which you can define a border

Unique Properties

These are the unique properties of a border field:

Key	Type	Description
borders	string	To have settings for all four border sides. If set to 'all', it will display fields for each side.

Output of a Border Field

The data from a border field is stored in the following keys:

Key	Description
color	The color of the border
labels	array
style	The style of the border, such as 'dotted'
width	The width of the border, defined as ['amount' => '', 'unit' => '']

If the borders property is set to all, the above data is stored under top, right, left and bottom keys respectively.

 

Boxshadow

Displays a selection of fields for saving boxshadow settings.

Unique Properties

Key	Type	Description
labels	array	Optional custom labels for our boxshadow field. Should be in the following format: ['color' => __('Label above boxshadow color. Defaults to Boxshadow Color.'), 'dimensions' => __('Label above boxshadow dimensions. Defaults to Boxshadow X-Offset, Y-Offset, Blur and Spread.'), 'placeholder' => __('Label within boxshadow type dropdown. Defaults to Select Type.'), 'type' => __('Label above boxshadow type. Defaults to Boxshadow Type.')]
types	array	Optional custom options for the type of boxshadow, defaults to [ '' => __('Default', 'wpcf'), 'inset' => __('Inset', 'wp-custom-fields') ]
pixels	array	Optional custom options for the box-shadow x-position, y-position, blur and spread, defaults to ['x' => __('x-offset', 'wpcf'), 'y' => __('y-offset', 'wpcf'), 'blur' => __('blur', 'wpcf'), 'spread' => __('spread', 'wpcf')]

Output of a Boxshadow Field

The data from a boxshadow field is stored in the following keys:

Key	Description
x	The x-offset of the boxshadow as a numerical value
y	The y-offset of the boxshadow as a numerical value
blur	The blur of the boxshadow as a numerical value
spread	The spread of the boxshadow as a numerical value
type	The boxshadow type, such as 'inset'

 

Button

The button element allows adding a button to which you can bind a custom ajax action. This action is performed upon clicking the button.

Unique Properties

These are the unique properties of a button field:

Key	Type	Description
action	string	The name of the ajax action to perform, which was added through wp_ajax_(action) or wp_ajax_nopriv_(action).
data	array	The optional data passed to the ajax action. This data is json encoded as a data-attribute.
label	string	The label for the button
message	boolean	Whether to display a message or not. If set to true, it takes the data output from an ajax action. For example, it takes the message that an ajax action returns through wp_send_json_success().
style	string	Any additional button class supported by WordPress, such as button-primary

Output of a Button Field

The button field does not store any data by default.

 

Checkbox

The checkbox field renders one or more checkboxes.

Unique Properties

These are the unique properties of a checkbox field:

Key	Type	Description
options	array	The checkboxes that need to be displayed. See below for the accepted format.
single	boolean	By setting this to true, the value is stored as a single boolean using the field id instead of an array. Defaults to false. This only works if one option is defined, so it is particularly useful if you only have one checkbox.
style	string	The optional style for a checkbox. Accepts 'buttonset' to display the checkboxes as a set of buttons (particularly useful if you only use icons), 'switcher' or 'switcher switcher-disable' to display the checkboxes as a switcher field

Checkbox options need to be put in the following format. Either label or icon or optional, but one of them should be present.

[
    'checkbox_id' => ['label' => 'Label for this checkbox', 'icon' => 'material_icon']
]

Output of a Checkbox Field

The data from checkbox is stored as an array, where each key reflects the key as registered under the options property. If a checkbox is checked, such a key has a value of true, otherwise it is false. If the single property is set to true, the data is stored as a boolean.

 

Code

Displays a code input field, using CodeMirror to format the syntax.

Unique Properties

These are the unique properties for a code field:

Key	Type	Description
mode	string	The CodeMirror Language Mode. By default, this is 'htmlmixed'.

Output of a Code Field

The output is a string of the contents of the code field.

 

Colorpicker

Renders a colorpicker field, including a color opacity picker by default.

Unique Properties

These are the unique properties of a color field:

Key	Type	Description
alpha	boolean	If set to false, removes the opacity picker to define the alpha value of the color.

Output of a Colorpicker Field

The output is a string containing the rgb or rgba value for the selected color.

 

Datepicker

Renders a datepicker field using Flatpicker.

Unique Properties

These are the unique properties of a datepicker field:

Key	Type	Description
alt-format	string	Determines how a date is displayed, using common date-formats. Defaults to 'F j, Y'.
date-format	string	Determines how a date is stored, using common date-formats. Defaults to 'U'.
labels	array	Custom labels for the clear and toggle buttons within the datepicker. Should be in the following format: ['clear' => __('Label for the clear button. Defaults to Clear.'), 'toggle' => __('Label for toggle button. Defaults to Toggle.')]
locale	string	Can be used to set a locale. The localization file need to be included, which may be retrieved from Flatpicker
mode	string	Can be set to 'single', 'multiple' or 'range' to allow different kinds of date selection.
no-calendar	boolean	If set to true, the calendar is hidden.
week-numbers	boolean	If set to true, week numbers will show up in the calendar.

Output of a Datepicker Field

The output is a string in the format as defined under the date-format property.

 

Dimensions

Displays a number field with a unit select field along. By default, these units are common dimensions such as px, em and so forth.

Unique Properties

These are the unique properties of a dimensions field:

Key	Type	Description
borders	string	To have settings for all four sides. If set to 'all', it will display fields for each side.
step	float	The steps in the number field of the dimension. By default, this is 1, so only whole values can be entered. If this is set to 0.1 for example, values such as 0.3 are possible.
units	array	Set this to a custom array of units to overwrite the default units.

Output of a Dimensions Field

The data from a dimensions field is stored in the following keys:

Key	Description
amount	The numerical value for the dimension
unit	The unit for the dimension, such as 'px'

If the borders property is set to all, the above data is stored under top, right, left and bottom keys respectively.

 

Divider

Displays a divider, which is a field width border. This field does not have unique properties nor output.

 

Editor

Displays a TinyMCE editor.

Unique Properties

Key	Type	Description
settings	array	Custom editor settings as described under settings in the WordPress Codex.

Output of an Editor Field

The output of an editor field is a string of the data stored within the editor field.

 

Export

Displays exportable settings and a field for importing settings.

Unique Properties

These are the unique properties of the export field.

Key	Type	Description
key	string	To option key to which your data is stored. Most times, this is equal to the ID of your group of options. If your field is a metabox, it will automatically grab the metadata where the meta key matches the key.
context	string	To context determining the access to data (where a custom field is displayed on the backend). Should be either 'post', 'term', 'user' or 'options'.
labels	array	Custom labels for the Export field buttons. Should be in the following format: ['button' => __('Label for the import button. Defaults to Import'), 'label' => __('Label above export field.')]

Output of a Export Field

The export field does not save any additional data, but pulls the data from your defined options ID.

 

Heading

Displays a heading. Useful to divide several sections of options.

Unique Properties

These are the unique properties of the heading field.

Key	Type	Description
collapse	array	Adds an array of field ids that should be collapsed. These fields will be hidden, unless you click the heading. The heading will also have an arrow indicator, indicating a collapsible section. Can be used to create collapsible sections.
subtitle	string	Adds an optional subtitle under the heading.

Output of a Heading Field

The heading field does not save any data.

 

HTML

Displays any html, filtered by wp_kses.

Unique Properties

These are the unique properties of the heading field.

Key	Type	Description
html	string	The HTML string that is being rendered by this field.

Data Output of a HTML Field

The HTML field does not save any data.

 

Icons

Adds a field in which one or more icons can be selected.

Unique Properties

These are the unique properties of the icons field.

Key	Type	Description
exclude	array	Icon sets to exclude from displaying. By default, the sets 'dashicons', 'font-awesome' and 'material' are included. For example, use ['dashicons'] to exclude dashicons
multiple	boolean	Whether one can select just one or multiple icons.

Output of an Icons Field

The data is stored either as an array with the names of the selected icons or a string with the name of one icon.

 

Input

Displays a plain input field. HTML5 input types are supported.

Unique Properties

These are the unique properties of an input field.

Key	Type	Description
class	string	Deprecated, and no longer used. Now replaced by the style key.
max	int	The maximum value of the input field. Used for number and range input types.
min	int	The minimum value of the input field. Used for number and range input types.
readonly	boolean	Makes the field read-only if set to true.
step	int	The steps in which a value can be increased, for example 1 or 0.1. Used for number and range input types.
style	string	A style class for the input field. Defaults to 'regular-text' and 'small-text' for number fields.
subtype	int	The optional HTML5 input type. Supports email, number, range, tel, text, url.

Output of an Input Field

The data is stored as a string.

 

Location

Displays a google map with an autosuggest field in which a location can be entered. Also, the street address, house number, postal code and city can be entered manually. This field requires to have a Google Maps API key registered upon initialization of the framework.

Unique Properties

Key	Type	Description
labels	array	Optional custom labels for the various labels above location fields. Default to the labels set in configurations of the field file, in src/fields/location.php.
search	string	Optional custom placeholder for the search field, defaults to 'Search for a location'

Output of a Location Field

The data of a location field is stored as an array with the following keys:

Key	Description
city	The city of the given address
lat	The latitude of the given address
lng	The longitude of the given address
number	The optional house number of the given address
postal_code	The optional postal code of the given address
street	The optional street of the given address

 

Media

Displays a field where one or multiple pieces of media, such as images or video, can be uploaded. It opens up a WordPress Media Modal in which media can be uploaded. Media fields are sortable!

Unique Properties

These are the unique properties of a media field.

Key	Type	Description
labels	array	Custom labels for our WP Media Modal. Should be in the following format: ['add' => __('Label for the addition button. Defaults to Add'), 'button' => __('Label for the Media Modal insert button. Defaults to Insert.'), 'title' => __('Title on top of the Media Modal. Defaults to Add Media.')]
multiple	boolean	Whether to allow multiple uploads or only one
subtype	string	The optional type of media that is allowed. By default, all types are supported. Also supports mime types such as video, image, audio, application, or any of the mime types supported by WordPress.
url	boolean	Whether to display media urls or not

Output of a Media Field

The media field saves data as a comma seperated string of attachment ids. This will be only one id if multiple is set to false.

 

Radio

The radio field displays a set of radio buttons

Unique Properties

These are the unique properties of a radio field:

Key	Type	Description
options	array	The checkboxes that need to be displayed. See below for the accepted format.
style	string	The optional style for a radio field. Accepts 'buttonset' to display the radio buttons as a set of buttons (if only icons are used), 'switcher' or ``'switcher switcher-disable'` to display the radio buttons as a switcher field

Radio field options need to be put in the following format. Either label or icon or optional, but one of them should be present.

[
    'radio_id' => ['label' => 'Label for this radio button', 'icon' => 'material_icon'],
    'radio_id_2' => ['label' => 'Label for this radio button', 'icon' => 'material_icon'],
]

Output of a Radio Field

The data from radio button is stored as a string, where the string matches the selected button.

 

Repeatable

Displays a group of fields which can be repeated. These fields are also sortable. Repeatable fields can not be nested yet.

Unique Properties

These are the unique properties of a repeatable field:

Key	Type	Description
add	string	The label for adding a group. Defaults to __('Add Group', 'wp-custom-fields').
remove	string	The label for removing a group. Defaults to __('Remove Group', 'wp-custom-fields').
collapse	boolean	If set to true, adds an arrow to toggle the display of fields in a group.
closed	boolean	If set to true, collapses a repeatable group by default.
fields	array	The fields that are in the repeatable group. These are added in the same way as fields are added to sections.
labels	array	Optional custom labels for the repeatable group. Should be in the following format: ['add' => __('Addition button label.'), 'remove' => __('Remove button label.')]

Output of a Repeatable Field

The data of a repeatable field is stored as an array, where each key represents the values of the fields of that particular group.

 

Select

The select field shows a dropdown select field. A select field may also load a host of (custom) posts, terms or users.

Unique Properties

These are the unique properties of a select field:

Key	Type	Description
mode	string	The mode for the field, either 'advanced' or 'plain'. Determines if Select2.js is used to render the field (when set to 'advanced', it is). Defaults to 'advanced'.
multiple	boolean	Whether to allow the selection of multiple options or not.
options	array	The array of options formatted as [option_value => __(Option Label)]
object	string	Allows filling the select field with data from users, posts or taxonomies. Accepts 'posts', 'term' or 'user' .
source	string	Defines from which post type or taxonomy options should be load, such as 'post', 'page' or 'category'. Is not required if the object property is set to 'user'.
relational	boolean	Makes this field relational if used as a post, term or user metabox, meaning it will automatically update the selected target posts, terms or users with itself. Requires object and eventually source to be set and can only be used within custom post, user and term metaboxes.

Output of a Select Field

The data for this field is saved as a string, or as an array of option values if multiple is set to true.

 

Slider

The slider field displays a range slider.

Unique Properties

These are the unique properties of a slider field:

Key	Type	Description
max	int	The maximum value of the slider
min	int	The minimum value of the slider
step	int	The steps into which the slider can increase, such as 0.5

Output of a Slider Field

The data for this field stored is a numeric value.

 

Textarea

Displays a textarea field.

Unique Properties

These are the unique properties of a textarea field:

Key	Type	Description
cols	int	The cols attribute of this textarea. Defaults to 70.
rows	int	The rows attribute of this textarea. Defaults to 7.

Output of a Textarea Field

The data for this field stored is stored as a text string.

 

Typography

Displays a field with typographic settings, such as color, font, font-size, line-height, font-style, test-align, text-transform and font-weight. If this field also influences styling (meaning the selector property has been set), it will show a field to load all font styles on the front-end.

Unique Properties

These are the unique properties of a typography field:

Key	Type	Description
labels	array	Optional custom labels for the typography field. Should be in the following format: ['normal' => __('The placeholder for loading normal fonts.'), 'italic' => __('The placeholder for loading italic fonts.'), 'select' => __('The placeholder for selecting a font'), 'weights' => __('The placeholder for font-weight.')]

Output of the Typography Field

The data for the typography field is stored as an array with the following keys:

Key	Description
color	The color of the font.
font	The selected font-family.
font_weight	The selected font-weight.
italic	The italic font-style of the font. Empty if not set.
line_spacing	The line-height of the font, stored in the keys amount (the value) and unit (the unit, such as px).
load	If extra fonts are loaded for italic or normal sets, in the format of the keys italic and normal.
size	The size of the font, stored in the keys amount (the value) and unit (the unit, such as px).
text_align	The alignment of the font, either left, right, center or ``justify`.
underline	The text-decoration of underline for the font. Empty if not set.
uppercase	The uppercase transformation of the font. Empty if not set.