As your users interact with your Admin panel, you might want to store their preferences in a persistent manner, so that when they revisit the Admin panel, 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:
Listview active columns, and their order, that users define
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:
Navcomponent, and you've built in an "accordion-style" UI, you might want to store the
collapsedstate of each Nav collapsible item. This way, if an editor returns to the panel, their
Navstate is persisted automatically
recentlyAccesseddocuments to give admin editors an easy shortcut back to their recently accessed documents on the
Payload automatically creates an internally used
_preferences collection that stores user preferences. Each document in the
_preferences collection contains the following shape:
|A unique ID for each preference stored.|
|A unique |
|The ID of the |
|The value of the preference. Can be any data shape that you need.|
|A timestamp of when the preference was created.|
|A timestamp set to the last time the preference was updated.|
Preferences are available to both GraphQL and REST APIs.
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:
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.
keyof your preference to retrieve.
Also async, this method provides you with an easy way to set a user preference. It returns
keyof your preference to set.
valueof your preference that you're looking to set.
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.