Global Hooks

Globals feature the ability to define the following hooks:

beforeValidate
beforeChange
afterChange
beforeRead
afterRead

Config

All Global Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.

globals/example-hooks.js

1import { GlobalConfig } from 'payload/types';
2
3const ExampleHooks: GlobalConfig = {
slug: 'header',
fields: [
  { name: 'title', type: 'text'},
]
hooks: {
  beforeValidate: [(args) => {...}],
  beforeChange: [(args) => {...}],
  beforeRead: [(args) => {...}],
  afterChange: [(args) => {...}],
  afterRead: [(args) => {...}],
}
15}

beforeValidate

Runs before the update operation. This hook allows you to add or format data before the incoming data is validated.

1import { GlobalBeforeValidateHook } from 'payload/types'
2
3const beforeValidateHook: GlobalBeforeValidateHook = async ({
4  data, // incoming data to update or create with
5  req, // full express request
6  originalDoc, // original document
7}) => {
8  return data // Return data to update the document with
9}

Immediately following validation, beforeChange hooks will run within the update operation. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.

1import { GlobalBeforeChangeHook } from 'payload/types'
2
3const beforeChangeHook: GlobalBeforeChangeHook = async ({
4  data, // incoming data to update or create with
5  req, // full express request
6  originalDoc, // original document
7}) => {
8  return data // Return data to update the document with
9}

afterChange

After a global is updated, the afterChange hook runs. Use this hook to purge caches of your applications, sync site data to CRMs, and more.

1import { GlobalAfterChangeHook } from 'payload/types'
2
3const afterChangeHook: GlobalAfterChangeHook = async ({
4  doc, // full document data
5  previousDoc, // document data before updating the global
6  req, // full express request
7}) => {
8  return data
9}

beforeRead

Runs before findOne global operation is transformed for output by afterRead. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the doc argument.

1import { GlobalBeforeReadHook } from 'payload/types'
2
3const beforeReadHook: GlobalBeforeReadHook = async ({
4  doc, // full document data
5  req, // full express request
6}) => {...}

afterRead

Runs as the last step before a global is returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.

1import { GlobalAfterReadHook } from 'payload/types'
2
3const afterReadHook: GlobalAfterReadHook = async ({
4  doc, // full document data
5  req, // full express request
6  findMany, // boolean to denote if this hook is running against finding one, or finding many (useful in versions)
7}) => {...}

TypeScript

Payload exports a type for each Global hook which can be accessed as follows:

1import type {
GlobalBeforeValidateHook,
GlobalBeforeChangeHook,
GlobalAfterChangeHook,
GlobalBeforeReadHook,
GlobalAfterReadHook,
7} from 'payload/types'

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.