Field types overview

Last updated Oct 3, 20265 min read

A field type decides four things about a field: the control editors see, the database column that stores the value, how the value is cleaned before it is saved, and how it is printed on your site. Mass Custom Fields ships 32 field types in the free plugin. The Pro plugin adds four more (see Pro field types).

You choose the type when you add a field in WPM Fields › Field Groups (see Field groups). The picker groups types into Basic, Choice, Content, Relational and Layout.

How a value travels

An editor types or picks a value on the edit screen (or you call wpmcf_update_field(), or the REST API).
The field type sanitizes it. Anything the type cannot accept is dropped, and the field is saved empty (NULL). A value is never saved half-valid.
The value is written to the field's column in the field group table.
wpmcf_get_field() reads the column and returns a PHP value (a string, a number, a boolean or an array). wpmcf_the_field() and the [wpmcf_field] shortcode print a formatted, escaped version (a link, a label, an embed).

Reading is covered in Output, formats and escaping; the functions themselves are documented in Developer API.

All free types

The Type id is the value used in exports, the REST API and PHP. "Returns" is what wpmcf_get_field() gives you.

Basic

Type (UI label)	Type id	Column	Returns	Printed as	Page
Text	`text`	`VARCHAR(255)`	string	the text	Text fields
Text area	`textarea`	`LONGTEXT`	string (line breaks kept)	the text	Text fields
Number	`number`	`DECIMAL(20,6)`	`int` or `float`	the number	Number and range
Range	`range`	`DECIMAL(20,6)`	`int` or `float`	the number	Number and range
Email	`email`	`VARCHAR(254)`	string	the address	Text fields
URL	`url`	`TEXT`	string	the URL	Text fields
Password	`password`	`VARCHAR(255)`	the stored hash or sealed text, never the password	nothing (unless allowed)	Password
Color picker	`color_picker`	`VARCHAR(9)`	string like `#ff0000`	the hex code	Color and icon

Choice

Type (UI label)	Type id	Column	Returns	Printed as	Page
Select	`select`	`VARCHAR(191)`	the stored value (string)	the choice label	Choice fields
Radio buttons	`radio`	`VARCHAR(191)`	the stored value	the choice label	Choice fields
Checkboxes	`checkbox`	`JSON`	array of stored values	labels, comma separated	Choice fields
Button group	`button_group`	`VARCHAR(191)`	the stored value	the choice label	Choice fields
True / false	`true_false`	`TINYINT(1)`	`true` / `false`	"Yes" / "No" or your labels	Choice fields

Content

Type (UI label)	Type id	Column	Returns	Printed as	Page
Date	`date_picker`	`DATE`	string `Y-m-d`	formatted date	Date and time
Date and time	`date_time_picker`	`DATETIME`	string `Y-m-d H:i:s`	formatted date and time	Date and time
Time	`time_picker`	`TIME`	string `H:i:s`	formatted time	Date and time
Link	`link`	`JSON`	array `url`, `title`, `target`	an `<a>` element	Rich content
WYSIWYG editor	`wysiwyg`	`LONGTEXT`	HTML string	HTML with paragraphs and shortcodes	Rich content
oEmbed	`oembed`	`TEXT`	URL string	the provider's embed	Rich content
Image	`image`	`BIGINT(20) UNSIGNED`	attachment ID (int)	an `<img>` element	Image and file
File	`file`	`BIGINT(20) UNSIGNED`	attachment ID (int)	a link to the file	Image and file
Icon picker	`icon_picker`	`VARCHAR(191)`	`dashicons-…` class	the icon	Color and icon
Map	`map`	`JSON` + 2 coordinate columns	array `address`, `lat`, `lng`, `zoom`	address, map and link	Map

Relational

Type (UI label)	Type id	Column	Returns	Printed as	Page
Relationship	`relationship`	`JSON`	array of post IDs	a list of linked titles	Relational fields
Post object	`post_object`	`BIGINT(20) UNSIGNED`	one post ID (int)	a linked title	Relational fields
Page link	`page_link`	`BIGINT(20) UNSIGNED`	one post ID (int)	the permalink as a link	Relational fields
Taxonomy	`taxonomy`	`JSON`	array of term IDs	term names, linked	Relational fields
User	`user`	`JSON`	array of user IDs	display names	Relational fields

Layout

Type (UI label)	Type id	Column	Returns	Printed as	Page
Group	`group`	`JSON`	array keyed by sub-field	nothing (read a sub-field with `path`)	Group
Repeater	`repeater`	`JSON`	list of row arrays	an ordered list	Repeater
Accordion	`accordion`	none	none	nothing	Accordion and tab
Tab	`tab`	none	none	nothing	Accordion and tab

Accordion and Tab only organise the edit screen. They create no column and hold no value.

What each column type means for you

Column	Practical effect
`VARCHAR`, `CHAR`, `DATE`, `TIME`, `DATETIME`, numbers, `TINYINT`	Fast to filter and sort. You can add an index in the field's Constraints (see Field groups).
`TEXT`, `LONGTEXT`	Stores long text. Indexing uses a prefix of the text.
`JSON`	Stores structured values (lists, objects). Not indexable on its own.
Companion columns (Map)	The map keeps its latitude and longitude in two extra number columns so you can search by distance.

MySQL and MariaDB may reorder the keys of a JSON object (a Group, a Map, a Link). Always read values by key, never by position.

Choosing a type

You want to store	Use
A short label, a name, a phone number	Text
A paragraph without formatting	Text area
A price, a quantity, a rating	Number (or Range for a slider)
Yes/no	True / false
One option from a short list	Select, Radio buttons or Button group
Several options from a list	Checkboxes
A formatted article section	WYSIWYG editor
A button or call to action	Link
A video from YouTube or Vimeo	oEmbed
A picture or a downloadable document	Image / File
A location	Map
Another post, page, term or user	Post object, Page link, Relationship, Taxonomy, User
A set of related values (an address)	Group
A list of repeating blocks (FAQ items, team members)	Repeater
A secret an editor sets and your code only verifies	Password

Settings every type shares

Every type shares the same panels for default value, required, validation, display and conditional logic. See Settings every field has.

Limits to know about

Containers (Group, Repeater) cannot be placed inside another Group or Repeater. Password fields cannot be sub-fields either. See Group.
Programmatic SEO data sources accept only types that store one simple value: not Checkboxes, Link, Map, Relationship, Taxonomy, User, Group or Repeater.
Front-end forms (Pro) cannot show Icon picker, Map, Post object, Page link, Relationship or User fields, because their controls need the admin.
Field keys must not be SQL words or system column names. Keys such as on, when, order, group, index, id or uid, and keys that contain a double underscore (__), are refused when you save the group, for sub-fields as well. Use start_date instead of when, row_order instead of order.

Developers

You can register your own field types on the wpmcf/field_types/register action. See Developer API.

Troubleshooting

See Troubleshooting field types.

Was this page helpful?

Still stuck? Contact support