Managing User Preferences

As your users interact with the Admin Panel, you might want to store their preferences in a persistent manner, so that when they revisit the Admin Panel in a different session or from a different device, they can pick right back up where they left off.

Out of the box, Payload handles the persistence of your users' preferences in a handful of ways, including:

Columns in the Collection List View: their active state and order
The user's last active Locale
The "collapsed" state of blocks, array, and collapsible fields
The last-known state of the Nav component, etc.

Use Cases

This API is used significantly for internal operations of the Admin Panel, as mentioned above. But, if you're building your own React components for use in the Admin Panel, you can allow users to set their own preferences in correspondence to their usage of your components. For example:

If you have built a "color picker", you could "remember" the last used colors that the user has set for easy access next time
If you've built a custom Nav component, and you've built in an "accordion-style" UI, you might want to store the collapsed state of each Nav collapsible item. This way, if an editor returns to the panel, their Nav state is persisted automatically
You might want to store recentlyAccessed documents to give admin editors an easy shortcut back to their recently accessed documents on the Dashboard or similar
Many other use cases exist. Invent your own! Give your editors an intelligent and persistent editing experience.

Database

Payload automatically creates an internally used payload-preferences Collection that stores user preferences. Each document in the payload-preferences Collection contains the following shape:

Key	Value
`id`	A unique ID for each preference stored.
`key`	A unique `key` that corresponds to the preference.
`user.value`	The ID of the `user` that is storing its preference.
`user.relationTo`	The `slug` of the Collection that the `user` is logged in as.
`value`	The value of the preference. Can be any data shape that you need.
`createdAt`	A timestamp of when the preference was created.
`updatedAt`	A timestamp set to the last time the preference was updated.

APIs

Preferences are available to both GraphQL and REST APIs.

Adding or reading Preferences in your own components

The Payload Admin Panel offers a usePreferences hook. The hook is only meant for use within the Admin Panel itself. It provides you with two methods:

`getPreference`

This async method provides an easy way to retrieve a user's preferences by key. It will return a promise containing the resulting preference value.

Arguments

key: the key of your preference to retrieve.

`setPreference`

Also async, this method provides you with an easy way to set a user preference. It returns void.

Arguments:

key: the key of your preference to set.
value: the value of your preference that you're looking to set.

Example

Here is an example for how you can utilize usePreferences within your custom Admin Panel components. Note - this example is not fully useful and is more just a reference for how to utilize the Preferences API. In this case, we are demonstrating how to set and retrieve a user's last used colors history within a ColorPicker or similar type component.

1'use client'
2import React, { Fragment, useState, useEffect, useCallback } from 'react'
3import { usePreferences } from '@payloadcms/ui'
4
5const lastUsedColorsPreferenceKey = 'last-used-colors'
6
7export function CustomComponent() {
const { getPreference, setPreference } = usePreferences()
9
// Store the last used colors in local state
const [lastUsedColors, setLastUsedColors] = useState([])
12
// Callback to add a color to the last used colors
const updateLastUsedColors = useCallback(
  (color) => {
    // First, check if color already exists in last used colors.
    // If it already exists, there is no need to update preferences
    const colorAlreadyExists = lastUsedColors.indexOf(color) > -1
19
    if (!colorAlreadyExists) {
      const newLastUsedColors = [...lastUsedColors, color]
22
      setLastUsedColors(newLastUsedColors)
      setPreference(lastUsedColorsPreferenceKey, newLastUsedColors)
    }
  },
  [lastUsedColors, setPreference],
)
29
// Retrieve preferences on component mount
// This will only be run one time, because the `getPreference` method never changes
useEffect(() => {
  const asyncGetPreference = async () => {
    const lastUsedColorsFromPreferences = await getPreference(
      lastUsedColorsPreferenceKey,
    )
    setLastUsedColors(lastUsedColorsFromPreferences)
  }
39
  asyncGetPreference()
}, [getPreference])
42
return (
  <div>
    <button type="button" onClick={() => updateLastUsedColors('red')}>
      Use red
    </button>
    <button type="button" onClick={() => updateLastUsedColors('blue')}>
      Use blue
    </button>
    <button type="button" onClick={() => updateLastUsedColors('purple')}>
      Use purple
    </button>
    <button type="button" onClick={() => updateLastUsedColors('yellow')}>
      Use yellow
    </button>
    {lastUsedColors && (
      <Fragment>
        <h5>Last used colors:</h5>
        <ul>
          {lastUsedColors?.map((color) => <li key={color}>{color}</li>)}
        </ul>
      </Fragment>
    )}
  </div>
)
67}

Page Metadata

Managing User Preferences

Out of the box, Payload handles the persistence of your users' preferences in a handful of ways, including:

Columns in the Collection List View: their active state and order
The user's last active Locale
The "collapsed" state of blocks, array, and collapsible fields
The last-known state of the Nav component, etc.

Use Cases

If you have built a "color picker", you could "remember" the last used colors that the user has set for easy access next time
If you've built a custom Nav component, and you've built in an "accordion-style" UI, you might want to store the collapsed state of each Nav collapsible item. This way, if an editor returns to the panel, their Nav state is persisted automatically
You might want to store recentlyAccessed documents to give admin editors an easy shortcut back to their recently accessed documents on the Dashboard or similar
Many other use cases exist. Invent your own! Give your editors an intelligent and persistent editing experience.

Database

Payload automatically creates an internally used payload-preferences Collection that stores user preferences. Each document in the payload-preferences Collection contains the following shape:

Key	Value
`id`	A unique ID for each preference stored.
`key`	A unique `key` that corresponds to the preference.
`user.value`	The ID of the `user` that is storing its preference.
`user.relationTo`	The `slug` of the Collection that the `user` is logged in as.
`value`	The value of the preference. Can be any data shape that you need.
`createdAt`	A timestamp of when the preference was created.
`updatedAt`	A timestamp set to the last time the preference was updated.

key: the key of your preference to retrieve.

`setPreference`

Also async, this method provides you with an easy way to set a user preference. It returns void.

Arguments:

key: the key of your preference to set.
value: the value of your preference that you're looking to set.

Example

1'use client'
2import React, { Fragment, useState, useEffect, useCallback } from 'react'
3import { usePreferences } from '@payloadcms/ui'
4
5const lastUsedColorsPreferenceKey = 'last-used-colors'
6
7export function CustomComponent() {
const { getPreference, setPreference } = usePreferences()
9
// Store the last used colors in local state
const [lastUsedColors, setLastUsedColors] = useState([])
12
// Callback to add a color to the last used colors
const updateLastUsedColors = useCallback(
  (color) => {
    // First, check if color already exists in last used colors.
    // If it already exists, there is no need to update preferences
    const colorAlreadyExists = lastUsedColors.indexOf(color) > -1
19
    if (!colorAlreadyExists) {
      const newLastUsedColors = [...lastUsedColors, color]
22
      setLastUsedColors(newLastUsedColors)
      setPreference(lastUsedColorsPreferenceKey, newLastUsedColors)
    }
  },
  [lastUsedColors, setPreference],
)
29
// Retrieve preferences on component mount
// This will only be run one time, because the `getPreference` method never changes
useEffect(() => {
  const asyncGetPreference = async () => {
    const lastUsedColorsFromPreferences = await getPreference(
      lastUsedColorsPreferenceKey,
    )
    setLastUsedColors(lastUsedColorsFromPreferences)
  }
39
  asyncGetPreference()
}, [getPreference])
42
return (
  <div>
    <button type="button" onClick={() => updateLastUsedColors('red')}>
      Use red
    </button>
    <button type="button" onClick={() => updateLastUsedColors('blue')}>
      Use blue
    </button>
    <button type="button" onClick={() => updateLastUsedColors('purple')}>
      Use purple
    </button>
    <button type="button" onClick={() => updateLastUsedColors('yellow')}>
      Use yellow
    </button>
    {lastUsedColors && (
      <Fragment>
        <h5>Last used colors:</h5>
        <ul>
          {lastUsedColors?.map((color) => <li key={color}>{color}</li>)}
        </ul>
      </Fragment>
    )}
  </div>
)
67}

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

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Managing User Preferences

Use Cases

Database

APIs

Adding or reading Preferences in your own components

`getPreference`

`setPreference`

Example

Page Metadata

Managing User Preferences

Use Cases

Database

APIs

Adding or reading Preferences in your own components

`getPreference`

`setPreference`

Example