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.
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:
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.
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.
Some fields use their
name property as a unique identifier to store and retrieve from the database.
hash are all reserved field names which are sanitized from Payload's config and cannot be used.
Field validation is enforced automatically based on the field type and other properties such as
max value constraints on certain field types. This default behavior can be replaced by providing your own validate function for any field. 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 expects to return either
true or a string error message to display in both API responses and within the Admin panel.
There are two arguments available to custom validation functions.
|An object of the full collection or global document.|
|An object of the document data limited to fields within the same parent to the field.|
|Will be "create" or "update" depending on the UI action or API call.|
|The value of the collection |
|The function for translating text, more.|
|The currently authenticated user object.|
|If the |
When supplying a field
validate function, Payload will use yours in place of the default. To make use of the default field validation in your custom logic you can import, call and return the result as needed.
Collections ID fields are generated automatically by default. An explicit
id field can be declared in the
fields array to override this behavior.
Users are then required to provide a custom ID value when creating a record through the Admin UI or API.
Valid ID types are
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
|You can programmatically show / hide fields based on what other fields are doing. Click here for more info.|
|All field components can be completely and easily swapped out for custom components that you define. Click here for more info.|
|Helper text to display with the field to provide more information for the editor user. Click here for more info.|
|Specify if the field should be rendered in the sidebar by defining |
|Restrict 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 |
|Attach raw CSS style properties to the root DOM element of a field.|
|Attach a CSS class name to the root DOM element of a field.|
|Setting a field to |
|If a field is |
|Setting a field's |
All Payload fields support the ability to swap in your own React components with ease. For more information, including examples, click here.
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
condition function should return a boolean that will control if the field should be displayed or not.
Fields can be prefilled with starting values using the
defaultValue property. This is used in the admin UI and also on the backend as API requests will be populated with missing or undefined field values. You can assign the defaultValue directly in the field configuration or supply a function for dynamic behavior. Values assigned during a create request on the server are added before validation occurs.
Functions are called with an optional argument object containing:
user- the authenticated user object
locale- the currently selected locale string
Here is an example of a defaultValue function that uses both:
A description can be configured three ways.
As shown above, you can simply provide a string that will show by the field, but there are use cases where you may want to create some dynamic feedback. By using a function or a component for the
description property you can provide realtime feedback as the user interacts with the form.
This example will display the number of characters allowed as the user types.
This component will count the number of characters entered.
You can import the internal Payload
Field type as well as other common field types as follows: