205 lines
9.2 KiB
Plaintext
205 lines
9.2 KiB
Plaintext
---
|
|
title: Fields Overview
|
|
label: Overview
|
|
order: 10
|
|
desc: Fields are the building blocks of Payload, find out how to add or remove a field, change field type, add hooks, define access control and validation.
|
|
keywords: overview, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
<Banner type="info">
|
|
Fields are the building blocks of Payload. Collections and Globals both use Fields to define the
|
|
shape of the data that they store. Payload offers a wide variety of field types - both simple and
|
|
complex.
|
|
</Banner>
|
|
|
|
Payload Fields define the shape of the data that will be stored in the [Database](../database/overview) as well as automatically construct the corresponding UI within the [Admin Panel](../admin/overview). Fields are defined as an array on [Collections](../configuration/collections) or [Globals](../configuration/globals) via the `fields` key.
|
|
|
|
There are many [field types](#field-types) to choose from, each of which allow you to write [Custom Validation](#validation) functions, [Conditional Logic](../admin/fields#conditional-logic), [Field-level Access Control](#field-level-access-control), [Field-level Hooks](#field-level-hooks), and so much more. You can also customize the appearance and behavior of fields in the Admin Panel, more details [here](../admin/fields).
|
|
|
|
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:**
|
|
|
|
```ts
|
|
import { CollectionConfig } from 'payload/types'
|
|
|
|
export const Page: CollectionConfig = {
|
|
slug: 'pages',
|
|
fields: [
|
|
{
|
|
name: 'myField',
|
|
type: 'text', // highlight-line
|
|
},
|
|
{
|
|
name: 'otherField',
|
|
type: 'checkbox', // highlight-line
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
## Field Types
|
|
|
|
- [Array](/docs/fields/array) - for repeating content, supports nested fields
|
|
- [Blocks](/docs/fields/blocks) - block-based fields, allowing powerful layout creation
|
|
- [Checkbox](/docs/fields/checkbox) - boolean true / false checkbox
|
|
- [Code](/docs/fields/code) - code editor that saves a string to the database
|
|
- [Collapsible](/docs/fields/collapsible) - used for admin layout, nest fields within a collapsible component
|
|
- [Date](/docs/fields/date) - date / time field that saves a timestamp
|
|
- [Email](/docs/fields/email) - validates the entry is a properly formatted email
|
|
- [Group](/docs/fields/group) - nest fields within an object
|
|
- [JSON](/docs/fields/json) - saves actual JSON in the database
|
|
- [Number](/docs/fields/number) - field that enforces that its value be a number
|
|
- [Point](/docs/fields/point) - geometric coordinates for location data
|
|
- [Radio](/docs/fields/radio) - radio button group, allowing only one value to be selected
|
|
- [Relationship](/docs/fields/relationship) - assign relationships to other collections
|
|
- [Rich Text](/docs/fields/rich-text) - fully extensible Rich Text editor
|
|
- [Row](/docs/fields/row) - used for admin field layout, no effect on data shape
|
|
- [Select](/docs/fields/select) - dropdown / picklist style value selector
|
|
- [Tabs](/docs/fields/tabs) - used for admin layout, nest fields within tabs
|
|
- [Text](/docs/fields/text) - simple text input
|
|
- [Textarea](/docs/fields/textarea) - allows a bit larger of a text editor
|
|
- [Upload](/docs/fields/upload) - allows local file and image upload
|
|
- [UI](/docs/fields/ui) - inject your own custom components and do whatever you need
|
|
|
|
## 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](/docs/hooks/overview#field-hooks).
|
|
|
|
## 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](/docs/access-control/overview#fields).
|
|
|
|
## Field Names
|
|
|
|
Some fields use their `name` property as a unique identifier to store and retrieve from the database. `__v`, `salt`, and `hash` are all reserved field names which are sanitized from Payload's config and cannot be used.
|
|
|
|
## Default Values
|
|
|
|
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:
|
|
|
|
```ts
|
|
const translation: {
|
|
en: 'Written by'
|
|
es: 'Escrito por'
|
|
}
|
|
|
|
const field = {
|
|
name: 'attribution',
|
|
type: 'text',
|
|
// highlight-start
|
|
defaultValue: ({ user, locale }) => `${translation[locale]} ${user.name}`,
|
|
// highlight-end
|
|
}
|
|
```
|
|
|
|
<Banner type="success">
|
|
You can use async defaultValue functions to fill fields with data from API requests.
|
|
</Banner>
|
|
|
|
## Validation
|
|
|
|
Field validation is enforced automatically based on the field type and other properties such as `required` or `min` and `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.
|
|
|
|
1. The value which is currently assigned to the field
|
|
2. An optional object with dynamic properties for more complex validation having the following:
|
|
|
|
| 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 |
|
|
| `t` | The function for translating text, [more](/docs/configuration/i18n) |
|
|
| `user` | An object containing the currently authenticated user |
|
|
| `payload` | If the `validate` function is being executed on the server, Payload will be exposed for easily running local operations. |
|
|
|
|
## Example
|
|
|
|
```ts
|
|
import { CollectionConfig } from 'payload/types'
|
|
|
|
export const Orders: CollectionConfig = {
|
|
slug: 'orders',
|
|
fields: [
|
|
{
|
|
name: 'customerNumber',
|
|
type: 'text',
|
|
validate: async (val, { operation }) => {
|
|
if (operation !== 'create') {
|
|
// skip validation on update
|
|
return true
|
|
}
|
|
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.'
|
|
},
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
For example:
|
|
|
|
```ts
|
|
import { text } from 'payload/fields/validations'
|
|
|
|
const field: Field = {
|
|
name: 'notBad',
|
|
type: 'text',
|
|
validate: (val, args) => {
|
|
if (val === 'bad') {
|
|
return 'This cannot be "bad"'
|
|
}
|
|
// highlight-start
|
|
return text(val, args)
|
|
// highlight-end
|
|
},
|
|
}
|
|
```
|
|
|
|
## Customizable ID
|
|
|
|
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 `number` and `text`.
|
|
|
|
Example:
|
|
|
|
```ts
|
|
{
|
|
fields: [
|
|
{
|
|
name: 'id',
|
|
type: 'number',
|
|
},
|
|
],
|
|
}
|
|
```
|
|
|
|
## Admin Config
|
|
|
|
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](../admin/overview), such as their appearance or behavior. [More details](../admin/fields).
|
|
|
|
## TypeScript
|
|
|
|
You can import the internal Payload `Field` type as well as other common field types as follows:
|
|
|
|
```ts
|
|
import type { Field } from 'payload/types'
|
|
```
|