0
# User Preferences System
1

2
User preferences system for storing and managing user-specific settings, UI state, and document preferences in Payload CMS. This system allows users to persist their preferences across sessions, including collapsed fields, admin panel settings, and custom application state.
3

4
## Capabilities
5

6
### Find Preference
7

8
Retrieves a user preference by key.
9

10
```typescript { .api }
11
/**
12
 * Find a user preference by key
13
 * @param options - Options for finding the preference
14
 * @returns Promise resolving to the preference value or null
15
 */
16
function findPreference<T = any>(options: PreferenceRequest): Promise<T | null>;
17

18
interface PreferenceRequest {
19
  /** The preference key to find */
20
  key: string;
21
  /** The user object */
22
  user: User;
23
  /** Express request object */
24
  req: PayloadRequest;
25
  /** Whether to override access control */
26
  overrideAccess?: boolean;
27
}
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
import payload from "payload";
34

35
// Find user's collapsed field preferences
36
const collapsedFields = await payload.findPreference({
37
  key: "posts-fields",
38
  user: req.user,
39
  req,
40
});
41

42
// Find custom user settings
43
const dashboardSettings = await payload.findPreference({
44
  key: "dashboard-layout",
45
  user: req.user,
46
  req,
47
});
48
```
49

50
### Update Preference
51

52
Updates or creates a user preference.
53

54
```typescript { .api }
55
/**
56
 * Update or create a user preference
57
 * @param options - Options for updating the preference
58
 * @returns Promise resolving to the updated preference
59
 */
60
function updatePreference<T = any>(options: PreferenceUpdateRequest): Promise<Preference>;
61

62
interface PreferenceUpdateRequest extends PreferenceRequest {
63
  /** The value to store for this preference */
64
  value: T;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import payload from "payload";
72

73
// Update collapsed field state
74
await payload.updatePreference({
75
  key: "posts-fields",
76
  value: {
77
    fields: {
78
      content: { collapsed: ["advancedOptions"] },
79
      meta: { collapsed: ["seo", "social"] },
80
    },
81
  },
82
  user: req.user,
83
  req,
84
});
85

86
// Update custom settings
87
await payload.updatePreference({
88
  key: "theme-preference",
89
  value: { theme: "dark", sidebarCollapsed: true },
90
  user: req.user,
91
  req,
92
});
93
```
94

95
### Delete Preference
96

97
Deletes a user preference by key.
98

99
```typescript { .api }
100
/**
101
 * Delete a user preference by key
102
 * @param options - Options for deleting the preference
103
 * @returns Promise resolving to the deleted preference or null
104
 */
105
function deletePreference(options: PreferenceRequest): Promise<Preference | null>;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
import payload from "payload";
112

113
// Reset user preferences
114
await payload.deletePreference({
115
  key: "dashboard-layout",
116
  user: req.user,
117
  req,
118
});
119
```
120

121
## Types
122

123
```typescript { .api }
124
/**
125
 * Base preference document structure
126
 */
127
interface Preference {
128
  /** User ID that owns this preference */
129
  user: string;
130
  /** Collection slug the user belongs to */
131
  userCollection: string;
132
  /** Unique key for the preference */
133
  key: string;
134
  /** The stored preference value */
135
  value: { [key: string]: unknown } | unknown;
136
  /** Creation timestamp */
137
  createdAt?: Date;
138
  /** Last update timestamp */
139
  updatedAt?: Date;
140
}
141

142
/**
143
 * Document-level preferences for admin UI
144
 */
145
interface DocumentPreferences {
146
  /** Field-specific preferences */
147
  fields: FieldsPreferences;
148
}
149

150
/**
151
 * Field preferences including collapse states
152
 */
153
interface FieldsPreferences {
154
  [fieldName: string]: {
155
    /** Array of collapsed field paths */
156
    collapsed: CollapsedPreferences;
157
  };
158
}
159

160
/**
161
 * Array of field paths that are collapsed
162
 */
163
type CollapsedPreferences = string[];
164
```
165

166
## Common Use Cases
167

168
### Admin UI State Persistence
169

170
Preferences are commonly used to persist admin panel UI state across sessions:
171

172
```typescript
173
// Field collapse states
174
const fieldPrefs: DocumentPreferences = {
175
  fields: {
176
    content: { 
177
      collapsed: ["metadata", "seo"] 
178
    },
179
    sidebar: { 
180
      collapsed: ["relatedPosts"] 
181
    },
182
  },
183
};
184

185
await payload.updatePreference({
186
  key: `${collection}-fields`,
187
  value: fieldPrefs,
188
  user: req.user,
189
  req,
190
});
191
```
192

193
### Custom Application Settings
194

195
Store custom user settings for your application:
196

197
```typescript
198
// Theme and layout preferences
199
await payload.updatePreference({
200
  key: "app-settings",
201
  value: {
202
    theme: "dark",
203
    language: "en",
204
    timezone: "America/New_York",
205
    dashboardWidgets: ["analytics", "recent-posts"],
206
  },
207
  user: req.user,
208
  req,
209
});
210
```
211

212
### Per-Collection Settings
213

214
Maintain different settings for each collection:
215

216
```typescript
217
// Different list view settings per collection
218
await payload.updatePreference({
219
  key: "posts-list-view",
220
  value: {
221
    columns: ["title", "status", "author", "updatedAt"],
222
    limit: 25,
223
    sort: "-updatedAt",
224
  },
225
  user: req.user,
226
  req,
227
});
228

229
await payload.updatePreference({
230
  key: "media-list-view", 
231
  value: {
232
    columns: ["filename", "alt", "filesize", "createdAt"],
233
    limit: 50,
234
    sort: "filename",
235
  },
236
  user: req.user,
237
  req,
238
});
239
```