Collections feature the ability to define the following hooks:
Additionally, auth
-enabled collections feature the following hooks:
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/example-hooks.js
// Collection configmodule.exports = {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) => {...}],// Auth-enabled hooksafterLogin: [(args) => {...}],afterForgotPassword: [(args) => {...}],}}
The beforeOperation
Hook type 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
, refresh
, and forgotPassword
.
const beforeOperationHook = async ({args, // Original arguments passed into the operationoperation, // name of the operation}) => {return args; // Return operation arguments as necessary}
Runs before the create
and update
operations. This hook allows you to add or format data before the incoming data is validated.
const beforeValidateHook = async ({data, // incoming data to update or create withreq, // full express requestoperation, // name of the operation ie. 'create', 'update'originalDoc, // original document}) => {return data; // Return data to either create or update a document with}
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.
const beforeChangeHook = async ({data, // incoming data to update or create withreq, // full express requestoperation, // name of the operation ie. 'create', 'update'originalDoc, // original document}) => {return data; // Return data to either create or update a document with}
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.
const afterChangeHook = async ({doc, // full document datareq, // full express requestoperation, // name of the operation ie. 'create', 'update'}) => {return doc;}
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.
const beforeReadHook = async ({doc, // full document datareq, // full express requestquery, // JSON formatted query}) => {return doc;}
Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
const afterReadHook = async ({doc, // full document datareq, // full express requestquery, // JSON formatted queryfindMany, // boolean to denote if this hook is running against finding one, or finding many}) => {return doc;}
Runs before the delete
operation. Returned values are discarded.
const beforeDeleteHook = async ({req, // full express requestid, // id of document to delete}) => {...}
Runs immediately after the delete
operation removes records from the database. Returned values are discarded.
const afterDeleteHook = async ({req, // full express requestid, // id of document to deletedoc, // deleted document}) => {...}
For auth-enabled Collections, this hook runs after successful login
operations. You can optionally modify the user that is returned.
const afterLoginHook = async ({req, // full express requestuser, // user being logged intoken, // user token}) => {return user;}
For auth-enabled Collections, this hook runs after successful forgotPassword
operations. Returned values are discarded.
const afterLoginHook = async ({req, // full express requestuser, // user being logged intoken, // user token}) => {return user;}
Payload exports a type for each Collection hook which can be accessed as follows:
import type {CollectionBeforeOperationHook,CollectionBeforeValidateHook,CollectionBeforeChangeHook,CollectionAfterChangeHook,CollectionAfterReadHook,CollectionBeforeReadHook,CollectionBeforeDeleteHook,CollectionAfterDeleteHook,CollectionBeforeLoginHook,CollectionAfterLoginHook,CollectionAfterForgotPasswordHook,} from 'payload/types';// Use hook types here...}