payload/docs/Hooks/config.mdx

---
title: Hooks Config
label: Config
order: 10
---

<Banner type="info">
	Hooks allow intervention before or after any internal operation.

  Payload has extensive support for hooks, at both the document-level and field-level.
</Banner>

## Hook Types

- [Payload Hooks](#payload-hooks)
- [Collection Hooks](#collection-hooks)
- [Field Hooks](#field-hooks)
- [Error Hook](#error-hook)

## Payload Hooks

Discuss the afterError hook here, including how it is only used in REST API currently.

## Collection Hooks

Collection can be executed at any point in the modification or retrieval of a collection.

Collection Hooks available:

_TODO: Fix anchor links_

- [beforeOperation](#beforeOperation)
- [beforeValidate](#beforeValidate)
- [beforeChange](#beforeChange)
- [afterChange](#afterChange)
- [beforeRead](#beforeRead)
- [afterRead](#afterRead)
- [beforeDelete](#beforeDelete)
- [afterDelete](#afterDelete)

### Usage

Configuration of collection hooks is done under a collection config in `payload.config.js`. They can either be created in-line or required from a separate file. Each hook is an array of functions to be run.

_TODO: Talk about async vs synchronous and concurrency_

```js
// Collection config
module.exports = {
  slug: 'public-user',
  fields: [
    { name: 'name', label: 'Name', type: 'text'},
  ]
  hooks: {
    // Before All Operations
    beforeOperation: [(args) => {...}],

    // Create and Update Operations
    beforeValidate: [(args) => {...}],
    beforeChange: [(args) => {...}],
    afterChange: [(args) => {...}],

    // Read Operations
    beforeRead: [(args) => {...}],
    afterRead: [(args) => {...}],

    // Delete Operations
    beforeDelete: [(args) => {...}],
    afterDelete: [(args) => {...}],

    // Login Operations
    beforeLogin: [(args) => {...}],
    afterLogin: [(args) => {...}],

    // After error
    afterError: [(args) => {...}],
  }
}
```

Each hook is an array of functions allowing for multiple to be combined as desired.

Configuration of hooks should be done in your `payload.config.js`

#### beforeOperation

Runs before any operation

```js
const beforeOperationHook = ({
  args, // Original arguments passed into the operation
  operation, // name of the operation
}) => {...}
```

Available Operations: `create`, `read`, `update`, `delete`, `refresh`, `forgotPassword`

#### beforeValidate

Runs before the `create` and `update` operations.

```js
const beforeValidateHook = ({
  data, // incoming document data
  req, // full express request
  operation, // name of the operation ie. 'create', 'update'
  originalDoc, // original document
}) => {...}
```

#### beforeChange

Runs before `create` and `update` operations, after validation.

```js
const beforeChangeHook = ({
  data, // incoming document data
  req, // full express request
  operation, // name of the operation ie. 'create', 'update'
  originalDoc, // original document
}) => {...}
```

#### afterChange

Runs after `create` and `update` operations.

```js
const afterChangeHook = ({
  doc, // full document data
  req, // full express request
  operation, // name of the operation ie. 'create', 'update'
}) => {...}
```

#### beforeRead

Runs before `find` and `findByID` operations.

```js
const beforeReadHook = ({
  doc, // full document data
  req, // full express request
  query, // JSON formatted query
}) => {...}
```

#### afterRead

Runs after `find` and `findByID` operations.

```js
const afterReadHook = ({
  doc, // full document data
  req, // full express request
  query, // JSON formatted query
}) => {...}
```

#### beforeDelete

Runs before `delete` operation

```js
const beforeDeleteHook = ({
  req, // full express request
  id, // id of document to delete
}) => {...}
```

#### afterDelete

Runs after `delete` operation

```js
const afterDeleteHook = ({
  req, // full express request
  id, // id of document to delete
  doc, // deleted document
}) => {...}
```

#### beforeLogin

Runs before `login` operation

```js
const beforeLoginHook = ({
  req, // full express request
}) => {...}
```

#### afterLogin

Runs after `login` operation

```js
const afterLoginHook = ({
  req, // full express request
  user, // user being logged in
  token, // user token
}) => {...}
```

#### afterError

Runs after an error occurs

_TODO: example usage_

## Field Hooks

Field can be executed at any point in the modification or retrieval of a collection field.

Field Hooks available:

- `beforeValidate`
- `beforeChange`
- `afterChange`
- `afterRead`

### Usage

```js
// Collection config
module.exports = {
  slug: 'public-user',
  fields: [
    {
      name: 'name',
      label: 'Name',
      type: 'text',
      hooks: {
        // Create and Update Operations
        beforeValidate: [(args) => {...}],
        beforeChange: [(args) => {...}],
        afterChange: [(args) => {...}],

        // Read Operations
        afterRead: [(args) => {...}],
      }
    },
  ],
}
```

#### beforeValidate

Runs before the `create` and `update` operations.

```js
const beforeValidateHook = ({
  value, // field value
  originalDoc, // original document
  data, // incoming document data
  operation, // name of the operation ie. 'create', 'update'
  req, // full express request
}) => {...}
```

#### beforeChange

Runs before the `create` and `update` operations, after validation.

```js
const beforeChangeHook = ({
  value, // field value
  originalDoc, // original document
  data, // incoming document data
  operation, // name of the operation ie. 'create', 'update'
  req, // full express request
}) => {...}
```

#### afterChange

Runs after `create` and `update` operations

```js
const afterChangeHook = ({
  value, // field value
  originalDoc, // original document
  data, // incoming document data
  operation, // name of the operation ie. 'create', 'update'
  req, // full express request
}) => {...}
```

#### afterRead

Runs after result as been retrieved from database

```js
const beforeChangeHook = ({
  value, // field value
  originalDoc, // original document
  data, // incoming document data
  operation, // name of the operation ie. 'create', 'update'
  req, // full express request
}) => {...}
```

## Hook Lifecycle

Hooks execute in the following order in relation to operations

`beforeOperation` is a special hook that runs _before all operations_.

### Create/Update Lifecycle

1. `beforeValidate` Field Hooks
2. `beforeValidate` Collection Hooks
3. Validate operation
4. `beforeChange` Field Hooks
5. `beforeChange` Collection Hooks
6. Create/Update against database
7. `afterChange` Field Hooks
8. `afterChange` Collection Hooks

### Find Lifecycle

1. `beforeRead` Collection Hooks
2. Find against database
3. `afterRead` Field Hooks
4. `afterRead` Collection Hooks