PayloadCMS Data Field Types: An Overview

In this guide, we’re going to go over data fields in PayloadCMS.

Out of the box, Payload CMS comes with a lot of different types of fields you can use to build out your collections and globals. In this video, we will start to go over three groups of fields that I’ve unofficially called the main fields, layout fields, and relationship fields.

This doesn’t cover every field available to you in Payload CMS, but it should get you started, since configuration options are similar across all fields. We also will not cover the Rich Text field in this guide. Instead, I will cover that in a future guide so we can make time to discuss it in depth.

We also will not cover all the configuration options for the fields as we go. Since most field types include the same types of config options, I will cover that in a separate guide.

Main fields

My grouping of these fields is not official by any means, but it helps me to think about these fields in different categories. The main fields are the data fields that most people will use day-to-day when building out their Payload CMS project.

Payload CMS calls all of these fields data fields, meaning they store data in the database. A few of the fields we will cover later, like the upload and relationship fields, are not included in this video even though they are data fields. These types of fields require more time and detail to explain than the following fields.

The fields we’ll go over in this video include the text, email, number, select, checkbox, and date fields.

Text field

The text field is your standard HTML text form field. This field saves your content as a string and only requires the name of the field and type options in order to initialize the field.

For the text field, you can use 3 admin options: placeholder, autocomplete, and set right-to-left. Placeholder allows you to fill in a value in the text input; autocomplete will allow you to tell the browser to either enable or disable autocomplete; and setting RTL allows you to set how the text is displayed from left-to-right to right-to-left.

Another handy feature for the text field is the “read only” admin option. While we’ll go over this in more detail later, this can be helpful if you want to create a field that can’t be edited. For example, if you wanted to create a URL field that was built from the slug and website domain, you could set up a hook that put all that together and wrote it to a text field that has readOnly enabled. This field doesn’t need to be edited by a user and can be taken care of by Payload.

Email field

The email field is the standard HTML email form field. Only the type and name options are required for this field. This field can be used to enforce that the value input here is in the format of a valid email address. This field saves the value as a string.

Similar to the text field, you can use a couple of admin fields. You can’t use RTL here, but you can use placeholder to define a placeholder string in the field and autocomplete to tell the browser to enable or disable autocomplete for this field.

It may also be valuable to use the admin configuration option called unique here, as well. If you have a collection of users where each user should have their own unique email address, you can set admin.unique to “true” to enforce that no copies of email addresses may be used.

Number

The number field is the standard HTML number form field. Only the type and name options are required for this field. This field saves the content as a number and validates that the value inputted is indeed a number.

This field uses the placeholder and autocomplete field admin config options as text and email, and introduces a new property called “step.” Step allows you to set the default increment or decrement value using the browser’s up and down arrows.

Select

The select field allows you to include a dropdown-style interactive feature in your collection or global. Name and type are required, just like the other fields so far. The select field introduces a new required field called options.

Your options are what show up in the dropdown. You can either use an array of strings or an array of objects that include a label string and a value string, which is how I prefer to do it.

If you want to be able to select more than one option in your select field, you may set the hasMany option to true to enable this feature.

You may not use a placeholder or the autocomplete feature for this field, but you do have the option to be able to sort and clear the select field. Setting admin.isClearable to true allows you to clear the field within the admin UI. Setting admin.isSortable will enable you to drag and drop the options in any order you choose. Neither of these fields are required, but you will need to enable hasMany in order to use isSortable.

Checkbox

The checkbox field stores a boolean value to your database. This comes in handy when you want to conditionally render something on the frontend when the field is checked—that is, set to true. You can also use this to conditionally render fields on the backend within Payload CMS.

Like other data fields, name and type are required options for this field. There are no admin configuration options specific to the checkbox field. You are still able to use some higher-level admin configuration options like description.

Date

The date field stores a Date in your database. Beyond that, it provides your admin panel with a customizable time picker interface. This allows you to have a graphical view of the date and time you want to use. Under the hood, this field uses the react-datepicker component.

Type and name are, of course, required for this field. There are no other required fields to initialize a date field.

There are many admin options available to you for the date field including a placeholder and the option to customize the date field appearance. We will go into more detail about these options in a future guide.

Final Thoughts

That’s it for Payload CMS’s data fields.

These fields are the basic building blocks of Payload CMS collections and globals. This is not an exhaustive list, but it will get you started with the most commonly used fields. Each field has a lot of flexibility and customization that we did not cover.