React Hooks

Payload provides a variety of powerful hooks that can be used within your own React components. With them, you can interface with Payload itself and build just about any type of complex customization you can think of—directly in familiar React code.

useField

The useField hook is used internally within every applicable Payload field component, and it manages sending and receiving a field's state from its parent form.

Outside of internal use, its most common use-case is in custom Field components. When you build a custom React Field component, you'll be responsible for sending and receiving the field's value from the form itself. To do so, import the useField hook as follows:

1import { useField } from 'payload/components/forms'
2
3type Props = { path: string }
4
5const CustomTextField: React.FC<Props> = ({ path }) => {
6  const { value, setValue } = useField<string>({ path })
7
8  return <input onChange={(e) => setValue(e.target.value)} value={value.path} />
9}

The useField hook accepts an args object and sends back information and helpers for you to make use of:

1const field = useField<string>({
2  path: 'fieldPathHere', // required
3  validate: myValidateFunc, // optional
4  disableFormData?: false, // if true, the field's data will be ignored
5  condition?: myConditionHere, // optional, used to skip validation if condition fails
6})
7
8// Here is what `useField` sends back
9const {
10  showError, // whether or not the field should show as errored
11  errorMessage, // the error message to show, if showError
12  value, // the current value of the field from the form
13  formSubmitted, // if the form has been submitted
14  formProcessing, // if the form is currently processing
15  setValue, // method to set the field's value in form state
16  initialValue, // the initial value that the field mounted with
17} = field;
18
19// The rest of your component goes here

useFormFields

There are times when a custom field component needs to have access to data from other fields, and you have a few options to do so. The useFormFields hook is a powerful and highly performant way to retrieve a form's field state, as well as to retrieve the dispatchFields method, which can be helpful for setting other fields' form states from anywhere within a form.

Thanks to the awesome package use-context-selector, you can retrieve a specific field's state easily. This is ideal because you can ensure you have an up-to-date field state, and your component will only re-render when that field's state changes.

You can pass a Redux-like selector into the hook, which will ensure that you retrieve only the field that you want. The selector takes an argument with type of [fields: Fields, dispatch: React.Dispatch<Action>]].

1import { useFormFields } from 'payload/components/forms'
2
3const MyComponent: React.FC = () => {
4  // Get only the `amount` field state, and only cause a rerender when that field changes
5  const amount = useFormFields(([fields, dispatch]) => fields.amount)
6
7  // Do the same thing as above, but to the `feePercentage` field
8  const feePercentage = useFormFields(([fields, dispatch]) => fields.feePercentage)
9
10  if (typeof amount?.value !== 'undefined' && typeof feePercentage?.value !== 'undefined') {
11    return <span>The fee is ${(amount.value * feePercentage.value) / 100}</span>
12  }
13}

useAllFormFields

To retrieve more than one field, you can use the useAllFormFields hook. Your component will re-render when any field changes, so use this hook only if you absolutely need to. Unlike the useFormFields hook, this hook does not accept a "selector", and it always returns an array with type of [fields: Fields, dispatch: React.Dispatch<Action>]].

You can do lots of powerful stuff by retrieving the full form state, like using built-in helper functions to reduce field state to values only, or to retrieve sibling data by path.

1import { useAllFormFields, reduceFieldsToValues, getSiblingData } from 'payload/components/forms';
2
3const ExampleComponent: React.FC = () => {
4  // the `fields` const will be equal to all fields' state,
5  // and the `dispatchFields` method is usable to send field state up to the form
6  const [fields, dispatchFields] = useAllFormFields();
7
8  // Pass in fields, and indicate if you'd like to "unflatten" field data.
9  // The result below will reflect the data stored in the form at the given time
10  const formData = reduceFieldsToValues(fields, true);
11
12  // Pass in field state and a path,
13  // and you will be sent all sibling data of the path that you've specified
14  const siblingData = getSiblingData(fields, 'someFieldName');
15
16  return (
17    // return some JSX here if necessary
18  )
19};

Updating other fields' values

If you are building a custom component, then you should use setValue which is returned from the useField hook to programmatically set your field's value. But if you're looking to update another field's value, you can use dispatchFields returned from useFormFields.

You can send the following actions to the dispatchFields function.

Action	Description
`ADD_ROW`	Adds a row of data (useful in array / block field data)
`DUPLICATE_ROW`	Duplicates a row of data (useful in array / block field data)
`MODIFY_CONDITION`	Updates a field's conditional logic result (true / false)
`MOVE_ROW`	Moves a row of data (useful in array / block field data)
`REMOVE`	Removes a field from form state
`REMOVE_ROW`	Removes a row of data from form state (useful in array / block field data)
`REPLACE_STATE`	Completely replaces form state
`UPDATE`	Update any property of a specific field's state

To see types for each action supported within the dispatchFields hook, check out the Form types here.

useForm

The useForm hook can be used to interact with the form itself, and sends back many methods that can be used to reactively fetch form state without causing rerenders within your components each time a field is changed. This is useful if you have action-based callbacks that your components fire, and need to interact with form state based on a user action.

The useForm hook returns an object with the following properties: |

Action	Description	Example
`fields`	Deprecated. This property cannot be relied on as up-to-date.
`submit`	Method to trigger the form to submit
`dispatchFields`	Dispatch actions to the form field state
`validateForm`	Trigger a validation of the form state
`createFormData`	Create a `multipart/form-data` object from the current form's state
`disabled`	Boolean denoting whether or not the form is disabled
`getFields`	Gets all fields from state
`getField`	Gets a single field from state by path
`getData`	Returns the data stored in the form
`getSiblingData`	Returns form sibling data for the given field path
`setModified`	Set the form\'s `modified` state
`setProcessing`	Set the form\'s `processing` state
`setSubmitted`	Set the form\'s `submitted` state
`formRef`	The ref from the form HTML element
`reset`	Method to reset the form to its initial state
`addFieldRow`	Method to add a row on an array or block field
`removeFieldRow`	Method to remove a row from an array or block field
`replaceFieldRow`	Method to replace a row from an array or block field

useCollapsible

The useCollapsible hook allows you to control parent collapsibles:

Property	Description
`collapsed`	State of the collapsible. `true` if open, `false` if collapsed
`isVisible`	If nested, determine if the nearest collapsible is visible. `true` if no parent is closed, `false` otherwise
`toggle`	Toggles the state of the nearest collapsible
`withinCollapsible`	Determine when you are within another collaspible

Example:

1import React from 'react'
2
3import { useCollapsible } from 'payload/components/utilities'
4
5const CustomComponent: React.FC = () => {
6  const { collapsed, toggle } = useCollapsible()
7  return (
8    <div>
9      <p className="field-type">I am {collapsed ? 'closed' : 'open'}</p>
10      <button onClick={toggle} type="button">
11        Toggle
12      </button>
13    </div>
14  )
15}

useDocumentInfo

The useDocumentInfo hook provides lots of information about the document currently being edited, including the following:

Property	Description
`collection`	If the doc is a collection, its collection config will be returned
`global`	If the doc is a global, its global config will be returned
`id`	If the doc is a collection, its ID will be returned
`preferencesKey`	The `preferences` key to use when interacting with document-level user preferences
`versions`	Versions of the current doc
`unpublishedVersions`	Unpublished versions of the current doc
`publishedDoc`	The currently published version of the doc being edited
`getVersions`	Method to trigger the retrieval of document versions
`docPermissions`	The current documents permissions. Collection document permissions fallback when no id is present (i.e. on create)
`getDocPermissions`	Method to trigger the retrieval of document level permissions

Example:

1import { useDocumentInfo } from 'payload/components/utilities'
2
3const LinkFromCategoryToPosts: React.FC = () => {
4  const { id } = useDocumentInfo()
5
6  // id will be undefined on the create form
7  if (!id) {
8    return null
9  }
10
11  return (
12    <a href={`/admin/collections/posts?where[or][0][and][0][category][in][0]=[${id}]`}>
13      View posts
14    </a>
15  )
16}

useLocale

In any custom component you can get the selected locale object with the useLocale hook. useLocalegives you the full locale object, consisting of a label, rtl(right-to-left) property, and then code. Here is a simple example:

1import { useLocale } from 'payload/components/utilities'
2
3const Greeting: React.FC = () => {
4  const locale = useLocale()
5
6  const trans = {
7    en: 'Hello',
8    es: 'Hola',
9  }
10
11  return <span> {trans[locale.code]} </span>
12}

useAuth

Useful to retrieve info about the currently logged in user as well as methods for interacting with it. It sends back an object with the following properties:

Property	Description
`user`	The currently logged in user
`logOut`	A method to log out the currently logged in user
`refreshCookie`	A method to trigger the silent refreshing of a user's auth token
`setToken`	Set the token of the user, to be decoded and used to reset the user and token in memory
`token`	The logged in user's token (useful for creating preview links, etc.)
`refreshPermissions`	Load new permissions (useful when content that effects permissions has been changed)
`permissions`	The permissions of the current user

1import { useAuth } from 'payload/components/utilities'
2import { User } from '../payload-types.ts'
3
4const Greeting: React.FC = () => {
5  const { user } = useAuth<User>()
6
7  return <span>Hi, {user.email}!</span>
8}

useConfig

Used to easily fetch the full Payload config.

1import { useConfig } from 'payload/components/utilities'
2
3const MyComponent: React.FC = () => {
4  const config = useConfig()
5
6  return <span>{config.serverURL}</span>
7}

useEditDepth

Sends back how many editing levels "deep" the current component is. Edit depth is relevant while adding new documents / editing documents in modal windows and other cases.

1import { useEditDepth } from 'payload/components/utilities'
2
3const MyComponent: React.FC = () => {
4  const editDepth = useEditDepth()
5
6  return <span>My component is {editDepth} levels deep</span>
7}

usePreferences

Returns methods to set and get user preferences. More info can be found here.

useTheme

Returns the currently selected theme (light, dark or auto), a set function to update it and a boolean autoMode, used to determine if the theme value should be set automatically based on the user's device preferences.

1import { useTheme } from 'payload/components/utilities'
2
3const MyComponent: React.FC = () => {
const { autoMode, setTheme, theme } = useTheme()
5
return (
  <>
    <span>The current theme is {theme} and autoMode is {autoMode}</span>
    <button
      type="button"
      onClick={() => setTheme(prev => prev === "light" ? "dark" : "light")}
    >
      Toggle theme
    </button>
  </>
  )
17}

useTableColumns

Returns methods to manipulate table columns

1import { useTableColumns } from 'payload/components/hooks'
2
3const MyComponent: React.FC = () => {
4  const { setActiveColumns } = useTableColumns()
5
6  const resetColumns = () => {
7    setActiveColumns(['id', 'createdAt', 'updatedAt'])
8  }
9
10  return (
11    <button
12      type="button"
13      onClick={resetColumns}
14    >
15      Reset columns
16    </button>
17  )
18}

useDocumentEvents

The useDocumentEvents hook provides a way of subscribing to cross-document events, such as updates made to nested documents within a drawer. This hook will report document events that are outside the scope of the document currently being edited. This hook provides the following:

Property	Description
`mostRecentUpdate`	An object containing the most recently updated document. It contains the `entitySlug`, `id` (if collection), and `updatedAt` properties
`reportUpdate`	A method used to report updates to documents. It accepts the same arguments as the `mostRecentUpdate` property.

Example:

1import { useDocumentEvents } from 'payload/components/hooks'
2
3const ListenForUpdates: React.FC = () => {
4  const { mostRecentUpdate } = useDocumentEvents()
5
6  return (
7    <span>
8      {JSON.stringify(mostRecentUpdate)}
9    </span>
10  )
11}

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

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

React Hooks

useField

useFormFields

useAllFormFields

Updating other fields' values

useForm

useCollapsible

useDocumentInfo

useLocale

useAuth

useConfig

useEditDepth

usePreferences

useTheme

useTableColumns

useDocumentEvents

Customizing CSS & SCSS

Related Help Topics