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.

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:

The useField hook accepts the following arguments:

The useField hook returns the following object:

Custom Field Components can be rendered on the server. When using a server component as a custom field component, you can access dynamic props from within any client component rendered by your custom server component. This is done using the useFieldProps hook. This is important because some fields can be dynamic, such as when nested in an array or blocks field. For example, items can be added, re-ordered, or deleted on-the-fly.

You can use the useFieldProps hooks to access dynamic props like path:

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

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.

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.

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

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:

The useCollapsible hook allows you to control parent collapsibles:

Example:

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

Example:

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:

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:

Used to easily retrieve the Payload Client Config.

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.

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

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.

Returns methods to manipulate table columns

Similar to useFieldProps, all Custom Cell Components are rendered on the server, and as such, only have access to static props at render time. But, some props need to be dynamic, such as the field value itself.

For this reason, dynamic props like cellData are managed in their own React context, which can be accessed using the useTableCell hook.

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:

Example: