Fields Overview

Fields are defined as an array on Collections and Globals via the fields key. They define the shape of the data that will be stored as well as automatically construct the corresponding Admin UI.

The required type property on a field determines what values it can accept, how it is presented in the API, and how the field will be rendered in the admin interface.

Simple collection with two fields:

const Pages = {
slug: 'pages',
fields: [
{
name: 'my-field',
type: 'text',
label: 'My Field',
},
{
name: 'other-field',
type: 'checkbox',
label: 'Other Field'
},
],
}

Field types

  • Array - for repeating content, supports nested fields
  • Blocks - block-based fields, allowing powerful layout creation
  • Checkbox - boolean true / false checkbox
  • Code - xode editor that saves a string to the database
  • Date - date / time field that saves a timestamp
  • Email - validates the entry is a properly formatted email
  • Group - nest fields within an object
  • Number - field that enforces that its value be a number
  • Radio - radio button group, allowing only one value to be selected
  • Relationship - assign relationships to other collections
  • Rich Text - fully extensible Rich Text editor
  • Row - used for admin field layout, no effect on data shape
  • Select - dropdown / picklist style value selector
  • Text - simple text input
  • Textarea - allows a bit larger of a text editor
  • Upload - allows local file and image upload

Field-level hooks

One of the most powerful parts about Payload is its ability for you to define field-level hooks that can control the logic of your fields to a fine-grained level. for more information about how to define field hooks, click here.

Field-level access control

In addition to being able to define access control on a document-level, you can define extremely granular permissions on a field by field level. For more information about field-level access control, click here.

Validation

You can provide your own validation function for all field types. It will be used on both the frontend and the backend, so it should not rely on any Node-specific packages. The validation function can be either synchronous or asynchronous and accepts the field's value and expects to return either true or a string error message to display in both API responses and within the Admin panel.

Example:

{
slug: 'orders',
fields: [
{
name: 'customerNumber',
type: 'text',
validate: async (val) => {
const response = await fetch(`https://your-api.com/customers/${val}`);
if (response.ok) {
return true;
}
return 'The customer number provided does not match any customers within our records.';
},
},
],
}

Admin config

In addition to each field's base configuration, you can define specific traits and properties for fields that only have effect on how they are rendered in the Admin panel. The following properties are available for all fields within the admin property:

OptionDescription
conditionYou can programmatically show / hide fields based on what other fields are doing. Click here for more info.
componentsAll field components can be completely and easily swapped out for custom components that you define. Click here for more info.
positionSpecify if the field should be rendered in the sidebar by defining position: 'sidebar'.
widthRestrict the width of a field. you can pass any string-based value here, be it pixels, percentages, etc. This property is especially useful when fields are nested within a Row type where they can be organized horizontally.
readOnlySetting a field to readOnly has no effect on the API whatsoever but disables the admin component's editability to prevent editors from modifying the field's value.
disabledIf a field is disabled, it is completely omitted from the Admin panel.
hiddenSetting a field's hidden property on its admin config will transform it into a hidden input type. Its value will still submit with the Admin panel's requests, but the field itself will not be visible to editors.

Conditional logic

You can show and hide fields based on what other fields are doing by utilizing conditional logic on a field by field basis. The condition property on a field's admin config accepts a function which takes two arguments:

  • data - the entire document's data that is currently being edited
  • siblingData - only the fields that are direct siblings to the field with the condition

The condition function should return a boolean that will control if the field should be displayed or not.

Example:

{
fields: [
{
name: 'enableGreeting',
type: 'checkbox',
defaultValue: false,
},
{
name: 'greeting',
type: 'text',
admin: {
condition: (data, siblingData) => {
if (data.enableGreeting) {
return true;
} else {
return false;
}
}
}
}
]
}

Custom components

All Payload fields support the ability to swap in your own React components with ease. For more information, including examples, click here.

Next

Array Field