Global Hooks

Global Hooks are Hooks that run on Global Documents. They allow you to execute your own logic during specific events of the Document lifecycle.

To add Hooks to a Global, use the hooks property in your Global Config:

1import type { GlobalConfig } from 'payload';
2
3export const GlobalWithHooks: GlobalConfig = {
4  // ...
5  hooks: { 
6    // ...
7  },
8}

Config Options

All Global Hooks accept an array of synchronous or asynchronous functions. Each Global Hook receives specific arguments based on its own type, and has the ability to modify specific outputs.

1import type { GlobalConfig } from 'payload';
2
3const GlobalWithHooks: GlobalConfig = {
4  // ...
5  hooks: {
6    beforeValidate: [(args) => {...}],
7    beforeChange: [(args) => {...}],
8    beforeRead: [(args) => {...}],
9    afterChange: [(args) => {...}],
10    afterRead: [(args) => {...}],
11  }
12}

beforeValidate

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

Please do note that this does not run before client-side validation. If you render a custom field component in your front-end and provide it with a validate function, the order that validations will run in is:

validate runs on the client
if successful, beforeValidate runs on the server
validate runs on the server

1import type { GlobalBeforeValidateHook } from 'payload'
2
3const beforeValidateHook: GlobalBeforeValidateHook = async ({
4  data,
5  req,
6  originalDoc,
7}) => {
8  return data
9}

The following arguments are provided to the beforeValidate hook:

Option	Description
`global`	The Global in which this Hook is running against.
`context`	Custom context passed between Hooks. More details.
`data`	The incoming data passed through the operation.
`originalDoc`	The Document before changes are applied.
`req`	The Web Request object. This is mocked for Local API operations.

beforeChange

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 type { GlobalBeforeChangeHook } from 'payload'
2
3const beforeChangeHook: GlobalBeforeChangeHook = async ({
4  data,
5  req,
6  originalDoc,
7}) => {
8  return data
9}

The following arguments are provided to the beforeChange hook:

Option	Description
`global`	The Global in which this Hook is running against.
`context`	Custom context passed between hooks. More details.
`data`	The incoming data passed through the operation.
`originalDoc`	The Document before changes are applied.
`req`	The Web Request object. This is mocked for Local API operations.

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 type { GlobalAfterChangeHook } from 'payload'
2
3const afterChangeHook: GlobalAfterChangeHook = async ({
4  doc,
5  previousDoc,
6  req,
7}) => {
8  return data
9}

The following arguments are provided to the afterChange hook:

Option	Description
`global`	The Global in which this Hook is running against.
`context`	Custom context passed between hooks. More details.
`doc`	The resulting Document after changes are applied.
`previousDoc`	The Document before changes were applied.
`req`	The Web Request object. This is mocked for Local API operations.

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 type { GlobalBeforeReadHook } from 'payload'
2
3const beforeReadHook: GlobalBeforeReadHook = async ({
4  doc,
5  req,
6}) => {...}

The following arguments are provided to the beforeRead hook:

Option	Description
`global`	The Global in which this Hook is running against.
`context`	Custom context passed between hooks. More details.
`doc`	The resulting Document after changes are applied.
`req`	The Web Request object. This is mocked for Local API operations.

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 type { GlobalAfterReadHook } from 'payload'
2
3const afterReadHook: GlobalAfterReadHook = async ({
4  doc,
5  req,
6  findMany,
7}) => {...}

The following arguments are provided to the beforeRead hook:

Option	Description
`global`	The Global in which this Hook is running against.
`context`	Custom context passed between hooks. More details.
`findMany`	Boolean to denote if this hook is running against finding one, or finding many (useful in versions).
`doc`	The resulting Document after changes are applied.
`query`	The Query of the request.
`req`	The Web Request object. This is mocked for Local API operations.

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'

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.