---
title: Field Hooks
label: Fields
order: 30
desc: Hooks can be added to any fields, and optionally modify the return value of the field before the operation continues.
keywords: hooks, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
---

Field-level hooks offer incredible potential for encapsulating your logic. They help to isolate concerns and package up functionalities to be easily reusable across your projects.

**Example use cases include:**

- Automatically add an `owner` relationship to a Document based on the `req.user.id`
- Encrypt / decrypt a sensitive field using `beforeValidate` and `afterRead` hooks
- Auto-generate field data using a `beforeValidate` hook
- Format incoming data such as kebab-casing a document `slug` with `beforeValidate`
- Restrict updating a document to only once every X hours using the `beforeChange` hook

**All field types provide the following hooks:**

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

## Config

Example field configuration:
```ts
import { Field } from 'payload/types';

const ExampleField: Field = {
  name: 'name',
  type: 'text',
  // highlight-start
  hooks: {
    beforeValidate: [(args) => {...}],
    beforeChange: [(args) => {...}],
    afterChange: [(args) => {...}],
    afterRead: [(args) => {...}],
  }
  // highlight-end
}
```

## Arguments and return values

All field-level hooks are formatted to accept the same arguments, although some arguments may be `undefined` based on which field hook you are utilizing.

<Banner type="success">
  <strong>Tip:</strong><br />
  It's a good idea to conditionally scope your logic based on which operation is executing. For example, if you are writing a <strong>beforeChange</strong> hook, you may want to perform different logic based on if the current <strong>operation</strong> is <strong>create</strong> or <strong>update</strong>.
</Banner>

#### Arguments

Field Hooks receive one `args` argument that contains the following properties:

| Option                   | Description                                                                                                                                                                                                           |
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **`data`**               | The data passed to update the document within `create` and `update` operations, and the full document itself in the `afterRead` hook.                                                                                 |
| **`siblingData`**        | The sibling data passed to a field that the hook is running against.                                                                                                                                                  |
| **`findMany`**           | Boolean to denote if this hook is running against finding one, or finding many within the `afterRead` hook.                                                                                                           |
| **`operation`**          | A string relating to which operation the field type is currently executing within. Useful within `beforeValidate`, `beforeChange`, and `afterChange` hooks to differentiate between `create` and `update` operations. |
| **`originalDoc`**        | The full original document in `update` operations. In the `afterChange` hook, this is the resulting document of the operation.                                                                                        |
| **`previousDoc`**        | The document before changes were applied, only in `afterChange` hooks.                                                                                                                                                |
| **`previousSiblingDoc`** | The sibling data from the previous document in `afterChange` hook.                                                                                                                                                    |
| **`req`**                | The Express `request` object. It is mocked for Local API operations.                                                                                                                                                  |
| **`value`**              | The value of the field.                                                                                                                                                                                               |

#### Return value

All field hooks can optionally modify the return value of the field before the operation continues. Field Hooks may optionally return the value that should be used within the field.

<Banner type="warning">
  <strong>Important</strong><br/>
  Due to GraphQL's typed nature, you should never change the type of data that you return from a field, otherwise GraphQL will produce errors. If you need to change the shape or type of data, reconsider Field Hooks and instead evaluate if Collection / Global hooks might suit you better.
</Banner>

## TypeScript

Payload exports a type for field hooks which can be accessed and used as follows:

```ts
import type { FieldHook } from 'payload/types';

// Field hook type is a generic that takes three arguments:
// 1: The document type
// 2: The value type
// 3: The sibling data type

type ExampleFieldHook = FieldHook<ExampleDocumentType, string, SiblingDataType>;

const exampleFieldHook: ExampleFieldHook = (args) => {
  const {
    value, // Typed as `string` as shown above
    data, // Typed as a Partial of your ExampleDocumentType
    siblingData, // Typed as a Partial of SiblingDataType
    originalDoc, // Typed as ExampleDocumentType
    operation,
    req,
  } = args;

  // Do something here...

  return value; // should return a string as typed above, undefined, or null
}
```
