Fields Overview

Fields are the building blocks of Payload. They define the schema of the Documents that will be stored in the Database, as well as automatically generate the corresponding UI within the Admin Panel.

There are many Field Types to choose from, ranging anywhere from simple text strings to nested arrays and blocks. Most fields save data to the database, while others are strictly presentational. Fields can have Custom Validations, Conditional Logic, Access Control, Hooks, and so much more.

Fields can be endlessly customized in their appearance and behavior without affecting their underlying data structure. Fields are designed to withstand heavy modification or even complete replacement through the use of Custom Field Components.

To configure fields, use the fields property in your Collection or Global config:

Payload provides a wide variety of built-in Field Types, each with its own unique properties and behaviors that determine which values it can accept, how it is presented in the API, and how it will be rendered in the Admin Panel.

To configure fields, use the fields property in your Collection or Global config:

There are three main categories of fields in Payload:

• Data Fields
• Presentational Fields
• Virtual Fields

To begin writing fields, first determine which Field Type best supports your application. Then author your field accordingly using the Field Options for your chosen field type.

Data Fields are used to store data in the Database. All Data Fields have a name property. This is the key that will be used to store the field's value.

Here are the available Data Fields:

• Array - for repeating content, supports nested fields
• Blocks - for block-based content, supports nested fields
• Checkbox - saves boolean true / false values
• Code - renders a code editor interface that saves a string
• Date - renders a date picker and saves a timestamp
• Email - ensures the value is a properly formatted email address
• Group - nests fields within a keyed object
• JSON - renders a JSON editor interface that saves a JSON object
• Number - saves numeric values
• Point - for location data, saves geometric coordinates
• Radio - renders a radio button group that allows only one value to be selected
• Relationship - assign relationships to other collections
• Rich Text - renders a fully extensible rich text editor
• Select - renders a dropdown / picklist style value selector
• Tabs (Named) - similar to group, but renders nested fields within a tabbed layout
• Text - simple text input that saves a string
• Textarea - similar to text, but allows for multi-line input
• Upload - allows local file and image upload

Presentational Fields do not store data in the database. Instead, they are used to organize and present other fields in the Admin Panel, or to add custom UI components.

Here are the available Presentational Fields:

• Collapsible - nests fields within a collapsible component
• Row - aligns fields horizontally
• Tabs (Unnamed) - nests fields within a tabbed layout. It is not presentational if the tab has a name.
• Group (Unnamed) - nests fields within a keyed object. It is not presentational if the group has a name.
• UI - blank field for custom UI components

Virtual fields display data that is not stored in the database, but is computed or derived from other fields.

Here are the available Virtual Fields:

• Join - achieves two-way data binding between fields

While Join fields are purpose-built virtual field types, any field type can be made virtual by adding the virtual property to its configuration. This allows you to create computed or relationship-derived fields that appear in API responses without being stored in the database.

Virtual fields are populated during API responses and can be used in the Admin Panel, but their values are not persisted to the database. This makes them ideal for displaying read-only computed data, relationship summaries, or formatted versions of existing field data.

Any field type can be made virtual by adding the virtual property to the field configuration. The virtual property can be configured in two ways:

When virtual is set to true, the field becomes virtual but doesn't automatically populate any data. You'll typically use Field-level Hooks to compute and populate the field's value:

When virtual is set to a string path, it creates a "virtual relationship field" that automatically resolves to data from another field in the document. This is particularly useful for displaying relationship data:

Virtual paths use dot notation to traverse relationships and nested data:

• author.name - Gets the name field from the author relationship
• author.profile.bio - Gets the bio field from a nested profile object within the author relationship
• categories.title - For hasMany relationships, returns an array of title values
• request.additionalStakeholders.email - Traverses multiple relationship levels

Important Requirements for Virtual Path Fields:

1. Source Relationship Required: The document must have a relationship field that corresponds to the first part of the virtual path. For example, if using virtual: 'author.name', there must be an author relationship field defined in the same collection.
2. Path Resolution: Virtual paths resolve at query time by following the relationships and extracting the specified field values.
3. Array Handling: When the virtual path traverses a hasMany relationship, the result will be an array of values.

Instead of just showing relationship IDs, display the actual names or titles:

For hasMany relationships, virtual fields return arrays:

Use hooks to create computed virtual fields:

Virtual fields appear in API responses alongside regular fields:

All fields require at least the type property. This matches the field to its corresponding Field Type to determine its appearance and behavior within the Admin Panel. Each Field Type has its own unique set of options based on its own type.

To set a field's type, use the type property in your Field Config:

All Data Fields require a name property. This is the key that will be used to store and retrieve the field's value in the database. This property must be unique amongst this field's siblings.

To set a field's name, use the name property in your Field Config:

Payload reserves various field names for internal use. Using reserved field names will result in your field being sanitized from the config.

The following field names are forbidden and cannot be used:

• __v
• salt
• hash
• file
• status - with Postgres Adapter and when drafts are enabled

In addition to being able to define Hooks on a document-level, you can define extremely granular logic field-by-field.

To define Field-level Hooks, use the hooks property in your Field Config:

For full details on Field-level Hooks, see the Field Hooks documentation.

In addition to being able to define Access Control on a document-level, you can define extremely granular permissions field-by-field.

To define Field-level Access Control, use the access property in your Field Config:

For full details on Field-level Access Control, see the Field Access Control documentation.

Fields can be optionally prefilled with initial values. This is used in both the Admin Panel as well as API requests to populate missing or undefined field values during the create or update operations.

To set a field's default value, use the defaultValue property in your Field Config:

Default values can be defined as a static value or a function that returns a value. When a defaultValue is defined statically, Payload's Database Adapters will apply it to the database schema or models.

Functions can be written to make use of the following argument properties:

• user - the authenticated user object
• locale - the currently selected locale string
• req - the PayloadRequest object

Here is an example of a defaultValue function:

Fields are automatically validated based on their Field Type and other Field Options such as required or min and max value constraints. If needed, however, field validations can be customized or entirely replaced by providing your own custom validation functions.

To set a custom field validation function, use the validate property in your Field Config:

Custom validation functions should return either true or a string representing the error message to display in API responses.

The following arguments are provided to the validate function:

The ctx argument contains full document data, sibling field data, the current operation, and other useful information such as currently authenticated user:

The following additional properties are provided in the ctx object:

You can return localized error messages by utilizing the translation function provided in the req object:

This way you can use Custom Translations as well as Payload's built in error messages (like validation:required used in the example above). For a full list of available translation strings, see the english translation file of Payload.

When using custom validation functions, Payload will use yours in place of the default. However, you might want to simply augment the default validation with your own custom logic.

To reuse default field validations, call them from within your custom validation function:

Here is a list of all default field validation functions:

When writing async or computationally heavy validation functions, it is important to consider the performance implications. Within the Admin Panel, validations are executed on every change to the field, so they should be as lightweight as possible and only run when necessary.

If you need to perform expensive validations, such as querying the database, consider using the event property in the ctx object to only run that particular validation on form submission.

To write asynchronous validation functions, use the async keyword to define your function:

All Collections automatically generate their own ID field. If needed, you can override this behavior by providing an explicit ID field to your config. This field should either be required or have a hook to generate the ID dynamically.

To define a custom ID field, add a top-level field with the name property set to id:

You can customize the appearance and behavior of fields within the Admin Panel through the admin property of any Field Config:

The following options are available:

Field Descriptions are used to provide additional information to the editor about a field, such as special instructions. Their placement varies from field to field, but typically are displayed with subtle style differences beneath the field inputs.

A description can be configured in three ways:

• As a string.
• As a function which returns a string. More details.
• As a React component. More details.

To add a Custom Description to a field, use the admin.description property in your Field Config:

Custom Descriptions can also be defined as a function. Description Functions are executed on the server and can be used to format simple descriptions based on the user's current Locale.

To add a Description Function to a field, set the admin.description property to a function in your Field Config:

All Description Functions receive the following arguments:

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 the following arguments:

The ctx object:

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

Example:

Within the Admin Panel, fields are represented in three distinct places:

• Field - The actual form field rendered in the Edit View.
• Cell - The table cell component rendered in the List View.
• Filter - The filter component rendered in the List View.
• Diff - The Diff component rendered in the Version Diff View

To swap in Field Components with your own, use the admin.components property in your Field Config:

The following options are available:

The Field Component is the actual form field rendered in the Edit View. This is the input that user's will interact with when editing a document.

To swap in your own Field Component, use the admin.components.Field property in your Field Config:

For details on how to build Custom Components, see Building Custom Components.

All Field Components receive the following props by default:

In addition to the above props, all Server Components will also receive the following props:

When swapping out the Field component, you are responsible for sending and receiving the field's value from the form itself.

To do so, import the useField hook from @payloadcms/ui and use it to manage the field's value:

When building Custom Field Components, you can import the client field props to ensure type safety in your component. There is an explicit type for the Field Component, one for every Field Type and server/client environment. The convention is to prepend the field type onto the target type, i.e. TextFieldClientComponent:

See each individual Field Type for exact type imports.

The Cell Component is rendered in the table of the List View. It represents the value of the field when displayed in a table cell.

To swap in your own Cell Component, use the admin.components.Cell property in your Field Config:

All Cell Components receive the same Default Field Component Props, plus the following:

For details on how to build Custom Components themselves, see Building Custom Components.

The Filter Component is the actual input element rendered within the "Filter By" dropdown of the List View used to represent this field when building filters.

To swap in your own Filter Component, use the admin.components.Filter property in your Field Config:

All Custom Filter Components receive the same Default Field Component Props.

For details on how to build Custom Components themselves, see Building Custom Components.

The Label Component is rendered anywhere a field needs to be represented by a label. This is typically used in the Edit View, but can also be used in the List View and elsewhere.

To swap in your own Label Component, use the admin.components.Label property in your Field Config:

All Custom Label Components receive the same Default Field Component Props.

For details on how to build Custom Components themselves, see Building Custom Components.

When building Custom Label Components, you can import the component types to ensure type safety in your component. There is an explicit type for the Label Component, one for every Field Type and server/client environment. The convention is to append LabelServerComponent or LabelClientComponent to the type of field, i.e. TextFieldLabelClientComponent.

Alternatively to the Description Property, you can also use a Custom Component as the Field Description. This can be useful when you need to provide more complex feedback to the user, such as rendering dynamic field values or other interactive elements.

To add a Description Component to a field, use the admin.components.Description property in your Field Config:

All Custom Description Components receive the same Default Field Component Props.

For details on how to build a Custom Components themselves, see Building Custom Components.

When building Custom Description Components, you can import the component props to ensure type safety in your component. There is an explicit type for the Description Component, one for every Field Type and server/client environment. The convention is to append DescriptionServerComponent or DescriptionClientComponent to the type of field, i.e. TextFieldDescriptionClientComponent.

The Error Component is rendered when a field fails validation. It is typically displayed beneath the field input in a visually-compelling style.

To swap in your own Error Component, use the admin.components.Error property in your Field Config:

All Error Components receive the Default Field Component Props.

For details on how to build Custom Components themselves, see Building Custom Components.

When building Custom Error Components, you can import the component types to ensure type safety in your component. There is an explicit type for the Error Component, one for every Field Type and server/client environment. The convention is to append ErrorServerComponent or ErrorClientComponent to the type of field, i.e. TextFieldErrorClientComponent.

The Diff Component is rendered in the Version Diff view. It will only be visible in entities with versioning enabled,

To swap in your own Diff Component, use the admin.components.Diff property in your Field Config:

All Error Components receive the Default Field Component Props.

For details on how to build Custom Components themselves, see Building Custom Components.

When building Custom Diff Components, you can import the component types to ensure type safety in your component. There is an explicit type for the Diff Component, one for every Field Type and server/client environment. The convention is to append DiffServerComponent or DiffClientComponent to the type of field, i.e. TextFieldDiffClientComponent.

With these properties you can add multiple components before and after the input element, as their name suggests. This is useful when you need to render additional elements alongside the field without replacing the entire field component.

To add components before and after the input element, use the admin.components.beforeInput and admin.components.afterInput properties in your Field Config:

All afterInput and beforeInput Components receive the same Default Field Component Props.

For details on how to build Custom Components, see Building Custom Components.

You can import the Payload Field type as well as other common types from the payload package. More details.