DemoCloud PricingDocsFor EnterpriseCommunity HelpBlog
New projectLogin
New projectLogin

Field Hooks

Field-level hooks offer incredible potential for encapsulating your logic. They help to isolate concerns and package up functionalities to be easily reusable across your projects.

Example use cases include:

  • Automatically add an owner relationship to a Document based on the req.user.id
  • Encrypt / decrypt a sensitive field using beforeValidate and afterRead hooks
  • Auto-generate field data using a beforeValidate hook
  • Format incoming data such as kebab-casing a document slug with beforeValidate
  • Restrict updating a document to only once every X hours using the beforeChange hook

All field types provide the following hooks:

  • beforeValidate
  • beforeChange
  • afterChange
  • afterRead

#
Config

Example field configuration:

import { Field } from 'payload/types';
const ExampleField: Field = {
name: 'name',
type: 'text',
hooks: {
beforeValidate: [(args) => {...}],
beforeChange: [(args) => {...}],
afterChange: [(args) => {...}],
afterRead: [(args) => {...}],
}
}

#
Arguments and return values

All field-level hooks are formatted to accept the same arguments, although some arguments may be undefined based on which field hook you are utilizing.

Arguments

Field Hooks receive one args argument that contains the following properties:

OptionDescription
dataThe data passed to update the document within create and update operations, and the full document itself in the afterRead hook.
siblingDataThe sibling data passed to a field that the hook is running against.
findManyBoolean to denote if this hook is running against finding one, or finding many within the afterRead hook.
operationA string relating to which operation the field type is currently executing within. Useful within beforeValidate, beforeChange, and afterChange hooks to differentiate between create and update operations.
originalDocThe full original document in update operations. In the afterChange hook, this is the resulting document of the operation.
previousDocThe document before changes were applied, only in afterChange hooks.
previousSiblingDocThe sibling data from the previous document in afterChange hook.
reqThe Express request object. It is mocked for Local API operations.
valueThe value of the field.
previousValueThe previous value of the field, before changes were applied, only in afterChange hooks.

Return value

All field hooks can optionally modify the return value of the field before the operation continues. Field Hooks may optionally return the value that should be used within the field.

#
TypeScript

Payload exports a type for field hooks which can be accessed and used as follows:

import type { FieldHook } from 'payload/types';
// Field hook type is a generic that takes three arguments:
// 1: The document type
// 2: The value type
// 3: The sibling data type
type ExampleFieldHook = FieldHook<ExampleDocumentType, string, SiblingDataType>;
const exampleFieldHook: ExampleFieldHook = (args) => {
const {
value, // Typed as `string` as shown above
data, // Typed as a Partial of your ExampleDocumentType
siblingData, // Typed as a Partial of SiblingDataType
originalDoc, // Typed as ExampleDocumentType
operation,
req,
} = args;
// Do something here...
return value; // should return a string as typed above, undefined, or null
}
Next

Global Hooks