0
# @payloadcms/ui
1

2
A comprehensive React UI component library for building Payload CMS admin interfaces. This package provides over 400 exports including form components, field elements, React hooks, providers, icons, and utilities for creating extensible admin interfaces.
3

4
## Package Information
5

6
- **Package Name**: @payloadcms/ui  
7
- **Package Type**: npm
8
- **Language**: TypeScript/React
9
- **Installation**: `npm install @payloadcms/ui`
10
- **Peer Dependencies**: React 19+, Next.js 15+, Payload CMS
11

12
## Core Imports
13

14
### Main Client-Side API
15

16
```typescript
17
import { 
18
  Button, 
19
  Table, 
20
  Form, 
21
  useField, 
22
  useAuth, 
23
  TextField 
24
} from '@payloadcms/ui';
25
```
26

27
### Shared Utilities (Server/Client Compatible)
28

29
```typescript
30
import { 
31
  buildFormState, 
32
  buildTableState, 
33
  parseSearchParams 
34
} from '@payloadcms/ui/shared';
35
```
36

37
### React Server Components  
38

39
```typescript
40
import { 
41
  DefaultListView, 
42
  DefaultEditView 
43
} from '@payloadcms/ui/rsc';
44
```
45

46
### Individual Elements
47

48
```typescript
49
import { Button } from '@payloadcms/ui/elements/Button';
50
import { PlusIcon } from '@payloadcms/ui/icons/Plus';
51
import { useField } from '@payloadcms/ui/forms/useField';
52
```
53

54
### Static Assets
55

56
```typescript
57
import { 
58
  payloadFavicon, 
59
  payloadFaviconDark, 
60
  payloadFaviconLight,
61
  staticOGImage 
62
} from '@payloadcms/ui/assets';
63
```
64

65
## Basic Usage
66

67
### Setting Up Providers
68

69
```typescript
70
import { 
71
  RootProvider, 
72
  AuthProvider, 
73
  ConfigProvider, 
74
  ThemeProvider 
75
} from '@payloadcms/ui';
76

77
function AdminApp({ config, user }) {
78
  return (
79
    <RootProvider>
80
      <ConfigProvider config={config}>
81
        <AuthProvider user={user}>
82
          <ThemeProvider theme="auto">
83
            <YourAdminInterface />
84
          </ThemeProvider>
85
        </AuthProvider>
86
      </ConfigProvider>
87
    </RootProvider>
88
  );
89
}
90
```
91

92
### Form Management
93

94
```typescript
95
import { Form, TextField, useForm } from '@payloadcms/ui';
96

97
function DocumentEditor() {
98
  const { submit, getData } = useForm();
99
  
100
  const handleSubmit = async () => {
101
    const formData = getData();
102
    await submit();
103
  };
104

105
  return (
106
    <Form onSubmit={handleSubmit}>
107
      <TextField 
108
        path="title" 
109
        label="Document Title"
110
        required 
111
      />
112
      <TextField 
113
        path="content" 
114
        label="Content"
115
      />
116
    </Form>
117
  );
118
}
119
```
120

121
### Field Hooks
122

123
```typescript
124
import { useField } from '@payloadcms/ui';
125

126
function CustomField() {
127
  const { value, setValue, showError, errorMessage } = useField<string>({
128
    path: 'customField',
129
    validate: (val) => val?.length > 0 || 'Field is required'
130
  });
131

132
  return (
133
    <div>
134
      <input
135
        value={value || ''}
136
        onChange={(e) => setValue(e.target.value)}
137
      />
138
      {showError && <span>{errorMessage}</span>}
139
    </div>
140
  );
141
}
142
```
143

144
## Architecture
145

146
The @payloadcms/ui package is structured around several key architectural patterns:
147

148
- **Provider-based Context System**: Global state management through React Context providers
149
- **Form State Management**: Centralized form handling with field-level validation and state
150
- **Component Composition**: Modular UI elements that can be combined and customized
151
- **Hook-based API**: React hooks for accessing state and functionality
152
- **TypeScript Integration**: Full type safety throughout the component API
153

154
## Capabilities
155

156
### Form System and Field Components
157

158
Complete form management with validation, state handling, and field components for all data types.
159

160
```typescript { .api }
161
function useField<TValue>(options?: {
162
  path?: string;
163
  validate?: (value: TValue) => string | true;
164
  disableFormData?: boolean;
165
}): FieldType<TValue>;
166

167
interface FieldType<TValue> {
168
  value: TValue;
169
  setValue: (value: TValue) => void;
170
  showError: boolean;
171
  errorMessage?: string;
172
  valid: boolean;
173
  disabled: boolean;
174
}
175
```
176

177
[Form System and Utilities](./forms.md)
178

179
### Field Components
180

181
Ready-to-use form field components for text, selection, rich content, and complex data types.
182

183
```typescript { .api }
184
interface TextFieldProps {
185
  path: string;
186
  label?: string;
187
  placeholder?: string;
188
  required?: boolean;
189
  readOnly?: boolean;
190
  validate?: (value: string) => string | true;
191
}
192

193
function TextField(props: TextFieldProps): JSX.Element;
194
function SelectField(props: SelectFieldProps): JSX.Element;
195
function RichTextField(props: RichTextFieldProps): JSX.Element;
196
```
197

198
[Field Components](./fields.md)
199

200
### React Hooks
201

202
Utility hooks for common admin interface needs including API requests, form state, and UI interactions.
203

204
```typescript { .api }
205
function usePayloadAPI<T>(url: string, options?: {
206
  initialData?: T;
207
  initialParams?: Record<string, unknown>;
208
}): [{
209
  data: T;
210
  isError: boolean;
211
  isLoading: boolean;
212
}, {
213
  setParams: (params: Record<string, unknown>) => void;
214
}];
215

216
function useAuth<T = any>(): AuthContext<T>;
217
function useDebounce<T>(value: T, delay: number): T;
218
```
219

220
[React Hooks](./hooks.md)
221

222
### UI Components and Elements
223

224
Comprehensive set of UI components for building admin interfaces including tables, modals, navigation, data display, view components, and brand graphics.
225

226
```typescript { .api }
227
interface ButtonProps {
228
  children?: React.ReactNode;
229
  type?: 'button' | 'submit' | 'reset';
230
  appearance?: 'primary' | 'secondary' | 'danger' | 'success';
231
  size?: 'small' | 'medium' | 'large';
232
  icon?: React.ReactNode;
233
  disabled?: boolean;
234
  onClick?: () => void;
235
}
236

237
function Button(props: ButtonProps): JSX.Element;
238
function Table(props: TableProps): JSX.Element;
239
function Modal(props: ModalProps): JSX.Element;
240
function DefaultListView(props: DefaultListViewProps): JSX.Element;
241
function DefaultEditView(props: DefaultEditViewProps): JSX.Element;
242
function PayloadIcon(props: PayloadIconProps): JSX.Element;
243
```
244

245
[UI Components](./components.md)
246

247
### Context Providers  
248

249
Provider components for managing global state including authentication, configuration, themes, and data flow.
250

251
```typescript { .api }
252
interface AuthProviderProps {
253
  children: React.ReactNode;
254
  user?: ClientUser;
255
  permissions?: SanitizedPermissions;
256
}
257

258
function AuthProvider(props: AuthProviderProps): JSX.Element;
259
function ConfigProvider(props: { config: ClientConfig; children: React.ReactNode }): JSX.Element;
260
function ThemeProvider(props: { theme: Theme; children: React.ReactNode }): JSX.Element;
261
```
262

263
[Context Providers](./providers.md)
264

265
### Icon Components
266

267
Complete icon set for common admin interface needs including navigation, actions, content types, and status indicators.
268

269
```typescript { .api }
270
interface IconProps {
271
  className?: string;
272
  size?: number | string;
273
  style?: React.CSSProperties;
274
}
275

276
function ChevronIcon(props: IconProps): JSX.Element;
277
function PlusIcon(props: IconProps): JSX.Element;
278
function EditIcon(props: IconProps): JSX.Element;
279
```
280

281
[Icon Components](./icons.md)
282

283
### Utilities and Helpers
284

285
Utility functions for common tasks including form state building, URL handling, validation, and data processing.
286

287
```typescript { .api }
288
function buildFormState(options: {
289
  fieldSchema: FieldSchema[];
290
  data?: Record<string, unknown>;
291
  operation?: 'create' | 'update';
292
  locale?: string;
293
}): FormState;
294

295
function parseSearchParams(search: string): Record<string, unknown>;
296
function formatAdminURL(args: { adminRoute: string; path: string }): string;
297
```
298

299
[Utilities and Helpers](./utilities.md)
300

301
## Types
302

303
```typescript { .api }
304
interface ClientUser {
305
  id: string;
306
  email?: string;
307
  [key: string]: unknown;
308
}
309

310
interface ClientConfig {
311
  routes: {
312
    admin: string;
313
    api: string;
314
  };
315
  collections: CollectionConfig[];
316
  globals: GlobalConfig[];
317
  localization?: LocalizationConfig;
318
}
319

320
interface AuthContext<T = any> {
321
  user: T | null;
322
  token?: string;
323
  permissions?: SanitizedPermissions;
324
  logOut: () => Promise<void>;
325
  refreshCookie: () => Promise<void>;
326
}
327

328
interface FormState {
329
  [path: string]: {
330
    value: unknown;
331
    valid: boolean;
332
    errorMessage?: string;
333
    disableFormData?: boolean;
334
  };
335
}
336

337
interface Theme {
338
  name: string;
339
  colors: Record<string, string>;
340
  breakpoints: Record<string, string>;
341
}
342

343
interface Column {
344
  field: string;
345
  label: string;
346
  accessor?: string;
347
  active?: boolean;
348
}
349

350
type ReactSelectOption = {
351
  label: string;
352
  value: string | number;
353
  disabled?: boolean;
354
};
355

356
interface StepNavItem {
357
  label: string;
358
  path: string;
359
  completed?: boolean;
360
}
361
```
362

363
This package provides the complete UI foundation for Payload CMS admin interfaces, enabling developers to build custom admin experiences while leveraging a robust, tested component system with consistent design patterns and comprehensive TypeScript support.