React Hooks

Payload provides a variety of powerful React Hooks that can be used within your own Custom Components, such as Custom Fields. With them, you can interface with Payload itself to build just about any type of complex customization you can think of.

useField

The useField hook is used internally within all field components. It manages sending and receiving a field's state from its parent form. When you build a Custom Field Component, you will be responsible for sending and receiving the field's value to and from the form yourself.

To do so, import the useField hook as follows:

1'use client'
2import type { TextFieldClientComponent } from 'payload'
3import { useField } from '@payloadcms/ui'
4
5export const CustomTextField: TextFieldClientComponent = ({ path }) => {
6  const { value, setValue } = useField({ path }) 
7
8  return (
9    <div>
10      <p>{path}</p>
11      <input
12        onChange={(e) => {
13          setValue(e.target.value)
14        }}
15        value={value}
16      />
17    </div>
18  )
19}

The useField hook accepts the following arguments:

Property	Description
`path`	If you do not provide a `path`, `name` will be used instead. This is the path to the field in the form data.
`validate`	A validation function executed client-side before submitting the form to the server. Different than Field-level Validation which runs strictly on the server.
`disableFormData`	If `true`, the field will not be included in the form data when the form is submitted.
`hasRows`	If `true`, the field will be treated as a field with rows. This is useful for fields like `array` and `blocks`.

The useField hook returns the following object:

1type FieldType<T> = {
errorMessage?: string
errorPaths?: string[]
filterOptions?: FilterOptionsResult
formInitializing: boolean
formProcessing: boolean
formSubmitted: boolean
initialValue?: T
path: string
permissions: FieldPermissions
readOnly?: boolean
rows?: Row[]
schemaPath: string
setValue: (val: unknown, disableModifyingForm?: boolean) => void
showError: boolean
valid?: boolean
value: T
18}

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

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

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.

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

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

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

useDocumentForm

The useDocumentForm hook works the same way as the useForm hook, but it always gives you access to the top-level Form of a document. This is useful if you need to access the document's Form context from within a child Form.

An example where this could happen would be custom components within lexical blocks, as lexical blocks initialize their own child Form.

1'use client'
2
3import { useDocumentForm } from '@payloadcms/ui'
4
5const MyComponent: React.FC = () => {
6  const { fields: parentDocumentFields } = useDocumentForm()
7
8  return (
9    <p>
10      The document's Form has ${Object.keys(parentDocumentFields).length} fields
11    </p>
12  )
13}

useCollapsible

The useCollapsible hook allows you to control parent collapsibles:

Property	Description
`isCollapsed`	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.
`isWithinCollapsible`	Determine when you are within another collapsible.

Example:

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

useDocumentInfo

The useDocumentInfo hook provides information about the current document being edited, including the following:

Property	Description
`action`	The URL attached to the action attribute on the underlying form element, which specifies where to send the form data when the form is submitted.
`apiURL`	The API URL for the current document.
`collectionSlug`	The slug of the collection if editing a collection document.
`currentEditor`	The user currently editing the document.
`docConfig`	Either the Collection or Global config of the document, depending on what is being edited.
`docPermissions`	The current document's permissions. Fallback to collection permissions when no id is present.
`documentIsLocked`	Whether the document is currently locked by another user. More details.
`getDocPermissions`	Method to retrieve document-level permissions.
`getDocPreferences`	Method to retrieve document-level user preferences. More details.
`globalSlug`	The slug of the global if editing a global document.
`hasPublishedDoc`	Whether the document has a published version.
`hasPublishPermission`	Whether the current user has permission to publish the document.
`hasSavePermission`	Whether the current user has permission to save the document.
`id`	If the doc is a collection, its ID will be returned.
`incrementVersionCount`	Method to increment the version count of the document.
`initialData`	The initial data of the document.
`isEditing`	Whether the document is being edited (as opposed to created).
`isInitializing`	Whether the document info is still initializing.
`isLocked`	Whether the document is locked. More details.
`lastUpdateTime`	Timestamp of the last update to the document.
`mostRecentVersionIsAutosaved`	Whether the most recent version is an autosaved version.
`preferencesKey`	The `preferences` key to use when interacting with document-level user preferences. More details.
`savedDocumentData`	The saved data of the document.
`setDocFieldPreferences`	Method to set preferences for a specific field. More details.
`setDocumentTitle`	Method to set the document title.
`setHasPublishedDoc`	Method to update whether the document has been published.
`title`	The title of the document.
`unlockDocument`	Method to unlock a document. More details.
`unpublishedVersionCount`	The number of unpublished versions of the document.
`updateDocumentEditor`	Method to update who is currently editing the document. More details.
`updateSavedDocumentData`	Method to update the saved document data.
`uploadStatus`	Status of any uploads in progress ('idle', 'uploading', or 'failed').
`versionCount`	The current version count of the document.

Example:

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

useListQuery

The useListQuery hook is used to subscribe to the data, current query, and other properties used within the List View. You can use this hook within any Custom Component rendered within the List View.

1'use client'
2import { useListQuery } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
5  const { data, query } = useListQuery()
6
7  // ...
8}

The useListQuery hook returns an object with the following properties:

Property	Description
`data`	The data that is being displayed in the List View.
`defaultLimit`	The default limit of items to display in the List View.
`defaultSort`	The default sort order of items in the List View.
`handlePageChange`	A method to handle page changes in the List View.
`handlePerPageChange`	A method to handle per page changes in the List View.
`handleSearchChange`	A method to handle search changes in the List View.
`handleSortChange`	A method to handle sort changes in the List View.
`handleWhereChange`	A method to handle where changes in the List View.
`modified`	Whether the query has been changed from its Query Preset.
`query`	The current query that is being used to fetch the data in the List View.

useSelection

The useSelection hook provides information on the selected rows in the List view as well as helper methods to simplify selection. The useSelection hook returns an object with the following properties:

Property	Description
`count`	The number of currently selected rows.
`getQueryParams`	A function that generates a query string based on the current selection state and optional additional filtering parameters.
`selectAll`	An enum value representing the selection range: `'allAvailable'`, `'allInPage'`, `'none'`, and `'some'`. The enum, `SelectAllStatus`, is exported for easier comparisons.
`selected`	A map of document id keys and boolean values representing their selection status.
`setSelection`	A function that toggles the selection status of a document row.
`toggleAll`	A function that toggles selection for all documents on the current page or selects all available documents when passed `true`.
`totalDocs`	The number of total documents in the collection.

Example:

1'use client'
2import { useSelection } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
5  const { count, toggleAll, totalDocs } = useSelection()
6
7  return (
8    <>
9      <span>
10        Selected {count} out of {totalDocs} docs!
11      </span>
12      <button type="button" onClick={() => toggleAll(true)}>
13        Toggle All Selections
14      </button>
15    </>
16  )
17}

useLocale

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

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

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

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

useConfig

Used to retrieve the Payload Client Config.

1'use client'
2import { useConfig } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
5  const { config } = useConfig()
6
7  return <span>{config.serverURL}</span>
8}

If you need to retrieve a specific collection or global config by its slug, getEntityConfig is the most efficient way to do so:

1'use client'
2import { useConfig } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
5  const { getEntityConfig } = useConfig()
6  const mediaConfig = getEntityConfig({ collectionSlug: 'media' })
7
8  return (
9    <span>The media collection has {mediaConfig.fields.length} fields.</span>
10  )
11}

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.

1'use client'
2import { useEditDepth } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
5  const editDepth = useEditDepth()
6
7  return <span>My component is {editDepth} levels deep</span>
8}

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.

1'use client'
2import { useTheme } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
const { autoMode, setTheme, theme } = useTheme()
6
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>
  </>
)
22}

useTableColumns

Returns methods to manipulate table columns

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

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:

1'use client'
2import { useDocumentEvents } from '@payloadcms/ui'
3
4const ListenForUpdates: React.FC = () => {
5  const { mostRecentUpdate } = useDocumentEvents()
6
7  return <span>{JSON.stringify(mostRecentUpdate)}</span>
8}

useStepNav

The useStepNav hook provides a way to change the step-nav breadcrumb links in the app header.

Property	Description
`setStepNav`	A state setter function which sets the `stepNav` array.
`stepNav`	A `StepNavItem` array where each `StepNavItem` has a label and optionally a url.

Example:

1'use client'
2import { type StepNavItem, useStepNav } from '@payloadcms/ui'
3import { useEffect } from 'react'
4
5export const MySetStepNavComponent: React.FC<{
6  nav: StepNavItem[]
7}> = ({ nav }) => {
8  const { setStepNav } = useStepNav()
9
10  useEffect(() => {
11    setStepNav(nav)
12  }, [setStepNav, nav])
13
14  return null
15}

usePayloadAPI

The usePayloadAPI hook is a useful tool for making REST API requests to your Payload instance and handling responses reactively. It allows you to fetch and interact with data while automatically updating when parameters change.

This hook returns an array with two elements:

An object containing the API response.
A set of methods to modify request parameters.

Example:

1'use client'
2import { usePayloadAPI } from '@payloadcms/ui'
3
4const MyComponent: React.FC = () => {
// Fetch data from a collection item using its ID
const [{ data, isError, isLoading }, { setParams }] = usePayloadAPI(
  '/api/posts/123',
  {
    initialParams: { depth: 1 },
  },
)
12
if (isLoading) return <p>Loading...</p>
if (isError) return <p>Error occurred while fetching data.</p>
15
return (
  <div>
    <h1>{data?.title}</h1>
    <button onClick={() => setParams({ cacheBust: Date.now() })}>
      Refresh Data
    </button>
  </div>
)
24}

Arguments:

Property	Description
`url`	The API endpoint to fetch data from. Relative URLs will be prefixed with the Payload API route.
`options`	An object containing initial request parameters and initial state configuration.

The options argument accepts the following properties:

Property	Description
`initialData`	Uses this data instead of making an initial request. If not provided, the request runs immediately.
`initialParams`	Defines the initial parameters to use in the request. Defaults to an empty object `{}`.

Returned Value:

The first item in the returned array is an object containing the following properties:

Property	Description
`data`	The API response data.
`isError`	A boolean indicating whether the request failed.
`isLoading`	A boolean indicating whether the request is in progress.

The second item is an object with the following methods:

Property	Description
`setParams`	Updates request parameters, triggering a refetch if needed.

Updating Data

The setParams function can be used to update the request and trigger a refetch:

1setParams({ depth: 2 })

This is useful for scenarios where you need to trigger another fetch regardless of the url argument changing.

useRouteTransition

Route transitions are useful in showing immediate visual feedback to the user when navigating between pages. This is especially useful on slow networks when navigating to data heavy or process intensive pages.

By default, any instances of Link from @payloadcms/ui will trigger route transitions dy default.

1import { Link } from '@payloadcms/ui'
2
3const MyComponent = () => {
4  return <Link href="/somewhere">Go Somewhere</Link>
5}

You can also trigger route transitions programmatically, such as when using router.push from next/router. To do this, wrap your function calls with the startRouteTransition method provided by the useRouteTransition hook.

1'use client'
2import React, { useCallback } from 'react'
3import { useTransition } from '@payloadcms/ui'
4import { useRouter } from 'next/navigation'
5
6const MyComponent: React.FC = () => {
7  const router = useRouter()
8  const { startRouteTransition } = useRouteTransition()
9
10  const redirectSomewhere = useCallback(() => {
11    startRouteTransition(() => router.push('/somewhere'))
12  }, [startRouteTransition, router])
13
14  // ...
15}

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

useDocumentForm

useCollapsible

useDocumentInfo

useListQuery

useSelection

useLocale

useAuth

useConfig

useEditDepth

usePreferences

useTheme

useTableColumns

useDocumentEvents

useStepNav

usePayloadAPI

Updating Data

useRouteTransition

Customizing CSS & SCSS