Collection Hooks

Collections feature the ability to define the following hooks:

beforeOperation
beforeValidate
beforeChange
afterChange
beforeRead
afterRead
beforeDelete
afterDelete
afterOperation

Additionally, auth-enabled collections feature the following hooks:

beforeLogin
afterLogin
afterLogout
afterRefresh
afterMe
afterForgotPassword
refresh
me

Config

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

collections/exampleHooks.js

1import { CollectionConfig } from 'payload/types';
2
3export const ExampleHooks: CollectionConfig = {
slug: 'example-hooks',
fields: [
  { name: 'name', type: 'text'},
],
hooks: {
  beforeOperation: [(args) => {...}],
  beforeValidate: [(args) => {...}],
  beforeDelete: [(args) => {...}],
  beforeChange: [(args) => {...}],
  beforeRead: [(args) => {...}],
  afterChange: [(args) => {...}],
  afterRead: [(args) => {...}],
  afterDelete: [(args) => {...}],
  afterOperation: [(args) => {...}],
18
  // Auth-enabled hooks
  beforeLogin: [(args) => {...}],
  afterLogin: [(args) => {...}],
  afterLogout: [(args) => {...}],
  afterRefresh: [(args) => {...}],
  afterMe: [(args) => {...}],
  afterForgotPassword: [(args) => {...}],
  refresh: [(args) => {...}],
  me: [(args) => {...}],
},
29}

beforeOperation

The beforeOperation hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.

Available Collection operations include create, read, update, delete, login, refresh, and forgotPassword.

1import { CollectionBeforeOperationHook } from 'payload/types'
2
3const beforeOperationHook: CollectionBeforeOperationHook = async ({
4  args, // original arguments passed into the operation
5  operation, // name of the operation
6  req, // full express request
7}) => {
8  return args // return modified operation arguments as necessary
9}

beforeValidate

Runs before the create and update operations. 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 the client-side validation. If you added a validate function, this would be the lifecycle:

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

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

Immediately following validation, beforeChange hooks will run within create and update operations. 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 { CollectionBeforeChangeHook } from 'payload/types'
2
3const beforeChangeHook: CollectionBeforeChangeHook = async ({
4  data, // incoming data to update or create with
5  req, // full express request
6  operation, // name of the operation ie. 'create', 'update'
7  originalDoc, // original document
8}) => {
9  return data // Return data to either create or update a document with
10}

afterChange

After a document is created or updated, the afterChange hook runs. This hook is helpful to recalculate statistics such as total sales within a global, syncing user profile changes to a CRM, and more.

1import { CollectionAfterChangeHook } from 'payload/types'
2
3const afterChangeHook: CollectionAfterChangeHook = async ({
4  doc, // full document data
5  req, // full express request
6  previousDoc, // document data before updating the collection
7  operation, // name of the operation ie. 'create', 'update'
8}) => {
9  return doc
10}

beforeRead

Runs before find and findByID operations are 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 { CollectionBeforeReadHook } from 'payload/types'
2
3const beforeReadHook: CollectionBeforeReadHook = async ({
4  doc, // full document data
5  req, // full express request
6  query, // JSON formatted query
7}) => {
8  return doc
9}

afterRead

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

1import { CollectionAfterReadHook } from 'payload/types'
2
3const afterReadHook: CollectionAfterReadHook = async ({
4  doc, // full document data
5  req, // full express request
6  query, // JSON formatted query
7  findMany, // boolean to denote if this hook is running against finding one, or finding many
8}) => {
9  return doc
10}

beforeDelete

Runs before the delete operation. Returned values are discarded.

1import { CollectionBeforeDeleteHook } from 'payload/types';
2
3const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
4  req, // full express request
5  id, // id of document to delete
6}) => {...}

afterDelete

Runs immediately after the delete operation removes records from the database. Returned values are discarded.

1import { CollectionAfterDeleteHook } from 'payload/types';
2
3const afterDeleteHook: CollectionAfterDeleteHook = async ({
4  req, // full express request
5  id, // id of document to delete
6  doc, // deleted document
7}) => {...}

afterOperation

The afterOperation hook can be used to modify the result of operations or execute side-effects that run after an operation has completed.

Available Collection operations include create, find, findByID, update, updateByID, delete, deleteByID, login, refresh, and forgotPassword.

1import { CollectionAfterOperationHook } from 'payload/types'
2
3const afterOperationHook: CollectionAfterOperationHook = async ({
4  args, // arguments passed into the operation
5  operation, // name of the operation
6  req, // full express request
7  result, // the result of the operation, before modifications
8}) => {
9  return result // return modified result as necessary
10}

beforeLogin

For auth-enabled Collections, this hook runs during login operations where a user with the provided credentials exist, but before a token is generated and added to the response. You can optionally modify the user that is returned, or throw an error in order to deny the login operation.

1import { CollectionBeforeLoginHook } from 'payload/types'
2
3const beforeLoginHook: CollectionBeforeLoginHook = async ({
4  req, // full express request
5  user, // user being logged in
6}) => {
7  return user
8}

afterLogin

For auth-enabled Collections, this hook runs after successful login operations. You can optionally modify the user that is returned.

1import { CollectionAfterLoginHook } from 'payload/types';
2
3const afterLoginHook: CollectionAfterLoginHook = async ({
4  req, // full express request
5  user, // user that was logged in
6  token, // user token
7}) => {...}

afterLogout

For auth-enabled Collections, this hook runs after logout operations.

1import { CollectionAfterLogoutHook } from 'payload/types';
2
3const afterLogoutHook: CollectionAfterLogoutHook = async ({
4  req, // full express request
5}) => {...}

afterRefresh

For auth-enabled Collections, this hook runs after refresh operations.

1import { CollectionAfterRefreshHook } from 'payload/types';
2
3const afterRefreshHook: CollectionAfterRefreshHook = async ({
4  req, // full express request
5  res, // full express response
6  token, // newly refreshed user token
7}) => {...}

afterMe

For auth-enabled Collections, this hook runs after me operations.

1import { CollectionAfterMeHook } from 'payload/types';
2
3const afterMeHook: CollectionAfterMeHook = async ({
4  req, // full express request
5  response, // response to return
6}) => {...}

afterForgotPassword

For auth-enabled Collections, this hook runs after successful forgotPassword operations. Returned values are discarded.

1import { CollectionAfterForgotPasswordHook } from 'payload/types'
2
3const afterForgotPasswordHook: CollectionAfterForgotPasswordHook = async ({
4  args, // arguments passed into the operation
5  context, 
6  collection, // The collection which this hook is being run on
7}) => {...}

refresh

For auth-enabled Collections, this hook allows you to optionally replace the default behavior of the refresh operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.

1import type { CollectionRefreshHook } from 'payload/types'
2
3const myRefreshHook: CollectionRefreshHook = async ({
4  args, // arguments passed into the `refresh` operation
5  user, // the user as queried from the database 
6}) => {...}

me

For auth-enabled Collections, this hook allows you to optionally replace the default behavior of the me operation with your own. If you optionally return a value from your hook, the operation will not perform its own logic and continue.

1import type { CollectionMeHook } from 'payload/types'
2
3const meHook: CollectionMeHook = async ({
4  args, // arguments passed into the `me` operation
5  user, // the user as queried from the database 
6}) => {...}

TypeScript

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

1import type {
CollectionBeforeOperationHook,
CollectionBeforeValidateHook,
CollectionBeforeChangeHook,
CollectionAfterChangeHook,
CollectionAfterReadHook,
CollectionBeforeReadHook,
CollectionBeforeDeleteHook,
CollectionAfterDeleteHook,
CollectionBeforeLoginHook,
CollectionAfterLoginHook,
CollectionAfterLogoutHook,
CollectionAfterRefreshHook,
CollectionAfterMeHook,
CollectionAfterForgotPasswordHook,
CollectionRefreshHook,
CollectionMeHook,
18} from 'payload/types'

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."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.