Collections feature the ability to define the following hooks:
Additionally, auth
-enabled collections feature the following hooks:
#
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
import { CollectionConfig } from 'payload/types';
export 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) => {...}],
beforeLogin: [(args) => {...}],
afterLogin: [(args) => {...}],
afterLogout: [(args) => {...}],
afterRefresh: [(args) => {...}],
afterMe: [(args) => {...}],
afterForgotPassword: [(args) => {...}],
},
}
#
beforeOperation
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
, login
, refresh
and forgotPassword
.
import { CollectionBeforeOperationHook } from 'payload/types';
const beforeOperationHook: CollectionBeforeOperationHook = async ({
args,
operation,
}) => {
return args;
}
#
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
import { CollectionBeforeOperationHook } from 'payload/types';
const beforeValidateHook: CollectionBeforeValidateHook = async ({
data,
req,
operation,
originalDoc,
}) => {
return data;
}
#
beforeChange
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.
import { CollectionBeforeChangeHook } from 'payload/types';
const beforeChangeHook: CollectionBeforeChangeHook = async ({
data,
req,
operation,
originalDoc,
}) => {
return data;
}
#
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.
import { CollectionAfterChangeHook } from 'payload/types';
const afterChangeHook: CollectionAfterChangeHook = async ({
doc,
req,
previousDoc,
operation,
}) => {
return doc;
}
#
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.
import { CollectionBeforeReadHook } from 'payload/types';
const beforeReadHook: CollectionBeforeReadHook = async ({
doc,
req,
query,
}) => {
return doc;
}
#
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.
import { CollectionAfterReadHook } from 'payload/types';
const afterReadHook: CollectionAfterReadHook = async ({
doc,
req,
query,
findMany,
}) => {
return doc;
}
#
beforeDelete
Runs before the delete
operation. Returned values are discarded.
import { CollectionBeforeDeleteHook } from 'payload/types';
const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
req,
id,
}) => {...}
#
afterDelete
Runs immediately after the delete
operation removes records from the database. Returned values are discarded.
import { CollectionAfterDeleteHook } from 'payload/types';
const afterDeleteHook: CollectionAfterDeleteHook = async ({
req,
id,
doc,
}) => {...}
#
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.
import { CollectionBeforeLoginHook } from 'payload/types';
const beforeLoginHook: CollectionBeforeLoginHook = async ({
req,
user,
}) => {
return user;
}
#
afterLogin
For auth-enabled Collections, this hook runs after successful login
operations. You can optionally modify the user that is returned.
import { CollectionAfterLoginHook } from 'payload/types';
const afterLoginHook: CollectionAfterLoginHook = async ({
req,
user,
token,
}) => {...}
#
afterLogout
For auth-enabled Collections, this hook runs after logout
operations.
import { CollectionAfterLogoutHook } from 'payload/types';
const afterLogoutHook: CollectionAfterLogoutHook = async ({
req,
}) => {...}
#
afterRefresh
For auth-enabled Collections, this hook runs after refresh
operations.
import { CollectionAfterRefreshHook } from 'payload/types';
const afterRefreshHook: CollectionAfterRefreshHook = async ({
req,
res,
token,
}) => {...}
#
afterMe
For auth-enabled Collections, this hook runs after me
operations.
import { CollectionAfterMeHook } from 'payload/types';
const afterMeHook: CollectionAfterMeHook = async ({
req,
response,
}) => {...}
#
afterForgotPassword
For auth-enabled Collections, this hook runs after successful forgotPassword
operations. Returned values are discarded.
import { CollectionAfterForgotPasswordHook } from 'payload/types';
const afterLoginHook: CollectionAfterForgotPasswordHook = async ({
req,
user,
token,
}) => {
return user;
}
#
TypeScript
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,
CollectionAfterLogoutHook,
CollectionAfterRefreshHook,
CollectionAfterMeHook,
CollectionAfterForgotPasswordHook,
} from 'payload/types';