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.
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 two main categories of fields in Payload:
To begin writing fields, first determine which Field Type best supports your application. Then to 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:
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:
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 within the Collection, Global, or nested group that it is defined in.
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
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 DB 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 objectlocale
- the currently selected locale stringHere 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:
Argument | Description |
---|---|
value | The value of the field being validated. |
ctx | An object with additional data and context. More details |
The ctx
argument contains full document data, sibling field data, the current operation, and other useful information such as currently authenticated in user:
The following additional properties are provided in the ctx
object:
Property | Description |
---|---|
data | An object containing the full collection or global document currently being edited. |
siblingData | An object containing document data that is scoped to only fields within the same parent of this field. |
operation | Will be create or update depending on the UI action or API call. |
id | The id of the current document being edited. id is undefined during the create operation. |
req | The current HTTP request object. Contains payload , user , etc. |
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:
Custom validation functions can also be asynchronous depending on your needs. This makes it possible to make requests to external services or perform other miscellaneous asynchronous logic.
To write asynchronous validation functions, use the async
keyword to define your function:
In addition to each field's base configuration, you can use the admin
key to specify traits and properties for fields that will only effect how they are rendered within the Admin Panel, such as their appearance or behavior.
For full details on Admin Options, see the Field Admin Options documentation.
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 will force users to provide a their own ID value when creating a record.
To define a custom ID field, add a new field with the name
property set to id
:
You can import the Payload Field
type as well as other common types from the payload
package. More details.