0
# Context Providers
1

2
Provider components for managing global state including authentication, configuration, themes, data flow, and UI state in Payload CMS admin interfaces.
3

4
## Core Providers
5

6
### RootProvider
7

8
Root provider that wraps all other context providers for the admin interface.
9

10
```typescript { .api }
11
interface RootProviderProps {
12
  children: React.ReactNode;
13
}
14

15
function RootProvider(props: RootProviderProps): JSX.Element;
16
```
17

18
Usage example:
19
```typescript
20
import { RootProvider } from '@payloadcms/ui';
21

22
function AdminApp() {
23
  return (
24
    <RootProvider>
25
      {/* All other providers and app content */}
26
    </RootProvider>
27
  );
28
}
29
```
30

31
### ConfigProvider
32

33
Provides Payload configuration context to child components.
34

35
```typescript { .api }
36
interface ConfigProviderProps {
37
  children: React.ReactNode;
38
  config: ClientConfig;
39
}
40

41
function ConfigProvider(props: ConfigProviderProps): JSX.Element;
42

43
function useConfig(): ClientConfigContext;
44

45
interface ClientConfigContext {
46
  config: ClientConfig;
47
  getEntityConfig: (slug: string, type: 'collections' | 'globals') => EntityConfig | null;
48
  setConfig: (config: ClientConfig) => void;
49
}
50
```
51

52
### AuthProvider
53

54
Authentication state and methods provider.
55

56
```typescript { .api }
57
interface AuthProviderProps {
58
  children: React.ReactNode;
59
  user?: ClientUser;
60
  permissions?: SanitizedPermissions;
61
}
62

63
function AuthProvider(props: AuthProviderProps): JSX.Element;
64

65
function useAuth<T = any>(): AuthContext<T>;
66

67
interface AuthContext<T> {
68
  user: T | null;
69
  token?: string;
70
  permissions?: SanitizedPermissions;
71
  logOut: () => Promise<void>;
72
  refreshCookie: () => Promise<void>;
73
  setUser: (user: T | null) => void;
74
  strategy?: string;
75
}
76
```
77

78
Usage example:
79
```typescript
80
import { AuthProvider, useAuth } from '@payloadcms/ui';
81

82
function AdminWrapper() {
83
  const { user, logOut } = useAuth();
84
  
85
  return (
86
    <div>
87
      {user ? (
88
        <div>
89
          Welcome, {user.email}
90
          <button onClick={logOut}>Logout</button>
91
        </div>
92
      ) : (
93
        <div>Please log in</div>
94
      )}
95
    </div>
96
  );
97
}
98
```
99

100
### TranslationProvider
101

102
Internationalization context for multi-language support.
103

104
```typescript { .api }
105
interface TranslationProviderProps {
106
  children: React.ReactNode;
107
}
108

109
function TranslationProvider(props: TranslationProviderProps): JSX.Element;
110

111
function useTranslation(): TranslationContext;
112

113
interface TranslationContext {
114
  t: (key: string, options?: Record<string, unknown>) => string;
115
  i18n: {
116
    language: string;
117
    languages: string[];
118
    changeLanguage: (lang: string) => void;
119
  };
120
}
121
```
122

123
### LocaleProvider
124

125
Current locale context provider.
126

127
```typescript { .api }
128
interface LocaleProviderProps {
129
  children: React.ReactNode;
130
  locale?: string;
131
}
132

133
function LocaleProvider(props: LocaleProviderProps): JSX.Element;
134

135
function useLocale(): LocaleContext;
136

137
interface LocaleContext {
138
  locale: string;
139
  setLocale: (locale: string) => void;
140
}
141
```
142

143
## UI State Providers
144

145
### ThemeProvider
146

147
Theme configuration and switching provider.
148

149
```typescript { .api }
150
interface ThemeProviderProps {
151
  children: React.ReactNode;
152
  theme?: 'light' | 'dark' | 'auto';
153
}
154

155
function ThemeProvider(props: ThemeProviderProps): JSX.Element;
156

157
function useTheme(): ThemeContext;
158

159
interface ThemeContext {
160
  theme: Theme;
161
  setTheme: (theme: 'light' | 'dark' | 'auto') => void;
162
  autoMode: boolean;
163
}
164
```
165

166
### WindowInfoProvider
167

168
Window size and breakpoint information provider.
169

170
```typescript { .api }
171
interface WindowInfoProviderProps {
172
  children: React.ReactNode;
173
}
174

175
function WindowInfoProvider(props: WindowInfoProviderProps): JSX.Element;
176

177
function useWindowInfo(): WindowInfoContext;
178

179
interface WindowInfoContext {
180
  width: number;
181
  height: number;
182
  breakpoint: {
183
    s: boolean;
184
    m: boolean;
185
    l: boolean;
186
  };
187
}
188
```
189

190
### RouteTransitionProvider
191

192
Route transition animations provider.
193

194
```typescript { .api }
195
interface RouteTransitionProviderProps {
196
  children: React.ReactNode;
197
}
198

199
function RouteTransitionProvider(props: RouteTransitionProviderProps): JSX.Element;
200

201
function useRouteTransition(): RouteTransitionContext;
202

203
interface RouteTransitionContext {
204
  inProgress: boolean;
205
  start: () => void;
206
  complete: () => void;
207
}
208
```
209

210
### ScrollInfoProvider
211

212
Scroll position information provider.
213

214
```typescript { .api }
215
interface ScrollInfoProviderProps {
216
  children: React.ReactNode;
217
}
218

219
function ScrollInfoProvider(props: ScrollInfoProviderProps): JSX.Element;
220

221
function useScrollInfo(): ScrollInfoContext;
222

223
interface ScrollInfoContext {
224
  y: number;
225
  x: number;
226
  direction: 'up' | 'down' | 'left' | 'right' | null;
227
}
228
```
229

230
## Document and Form Providers
231

232
### DocumentInfoProvider
233

234
Current document metadata provider.
235

236
```typescript { .api }
237
interface DocumentInfoProviderProps {
238
  children: React.ReactNode;
239
  id?: string | number;
240
  collection?: string;
241
  global?: string;
242
}
243

244
function DocumentInfoProvider(props: DocumentInfoProviderProps): JSX.Element;
245

246
function useDocumentInfo(): DocumentInfoContext;
247

248
interface DocumentInfoContext {
249
  id?: string | number;
250
  collection?: string;
251
  global?: string;
252
  hasPublishedDoc?: boolean;
253
  unpublishedVersions?: number;
254
  publishedVersions?: number;
255
  mostRecentVersionIsAutosaved?: boolean;
256
  initialState?: Record<string, unknown>;
257
}
258
```
259

260
### DocumentEventsProvider
261

262
Document-level event handling provider.
263

264
```typescript { .api }
265
interface DocumentEventsProviderProps {
266
  children: React.ReactNode;
267
}
268

269
function DocumentEventsProvider(props: DocumentEventsProviderProps): JSX.Element;
270

271
function useDocumentEvents(): DocumentEventsContext;
272

273
interface DocumentEventsContext {
274
  mostRecentUpdate: number;
275
  triggerUpdate: () => void;
276
}
277
```
278

279
### OperationProvider
280

281
Current CRUD operation context provider.
282

283
```typescript { .api }
284
interface OperationProviderProps {
285
  children: React.ReactNode;
286
  operation: 'create' | 'update';
287
}
288

289
function OperationProvider(props: OperationProviderProps): JSX.Element;
290

291
function useOperation(): string;
292
```
293

294
### EditDepthProvider
295

296
Nested edit depth tracking provider.
297

298
```typescript { .api }
299
interface EditDepthProviderProps {
300
  children: React.ReactNode;
301
  depth?: number;
302
}
303

304
function EditDepthProvider(props: EditDepthProviderProps): JSX.Element;
305

306
function useEditDepth(): number;
307
```
308

309
## Data Providers
310

311
### ListQueryProvider
312

313
List query and filtering state provider.
314

315
```typescript { .api }
316
interface ListQueryProviderProps {
317
  children: React.ReactNode;
318
  defaultSort?: string;
319
  defaultWhere?: Record<string, unknown>;
320
  defaultLimit?: number;
321
}
322

323
function ListQueryProvider(props: ListQueryProviderProps): JSX.Element;
324

325
function useListQuery(): ListQueryContext;
326

327
interface ListQueryContext {
328
  data: ListResult;
329
  query: ListQuery;
330
  refetch: () => Promise<void>;
331
  isLoading: boolean;
332
  error?: string;
333
  updateQuery: (query: Partial<ListQuery>) => void;
334
}
335
```
336

337
### SelectionProvider
338

339
Multi-select state management provider.
340

341
```typescript { .api }
342
interface SelectionProviderProps {
343
  children: React.ReactNode;
344
  docs: Record<string, unknown>[];
345
}
346

347
function SelectionProvider(props: SelectionProviderProps): JSX.Element;
348

349
function useSelection(): SelectionContext;
350

351
interface SelectionContext {
352
  selected: Map<string, Record<string, unknown>>;
353
  selectAll: () => void;
354
  deselectAll: () => void;
355
  toggleSelection: (id: string) => void;
356
  isSelected: (id: string) => boolean;
357
  count: number;
358
}
359
```
360

361
### PreferencesProvider
362

363
User preferences storage provider.
364

365
```typescript { .api }
366
interface PreferencesProviderProps {
367
  children: React.ReactNode;
368
}
369

370
function PreferencesProvider(props: PreferencesProviderProps): JSX.Element;
371

372
function usePreferences(): PreferencesContext;
373

374
interface PreferencesContext {
375
  getPreference: <T = any>(key: string) => T;
376
  setPreference: <T = any>(key: string, value: T) => void;
377
}
378
```
379

380
### ParamsProvider
381

382
Route parameters context provider.
383

384
```typescript { .api }
385
interface ParamsProviderProps {
386
  children: React.ReactNode;
387
  params: Record<string, string>;
388
}
389

390
function ParamsProvider(props: ParamsProviderProps): JSX.Element;
391

392
function useParams(): Record<string, string>;
393
```
394

395
## Advanced Providers
396

397
### ServerFunctionsProvider
398

399
Server-side function execution provider.
400

401
```typescript { .api }
402
interface ServerFunctionsProviderProps {
403
  children: React.ReactNode;
404
}
405

406
function ServerFunctionsProvider(props: ServerFunctionsProviderProps): JSX.Element;
407

408
function useServerFunctions(): ServerFunctionsContext;
409

410
interface ServerFunctionsContext {
411
  renderDocument: RenderDocumentServerFunction;
412
  [key: string]: (...args: any[]) => any;
413
}
414

415
type RenderDocumentServerFunction = (
416
  args: RenderDocumentArgs
417
) => Promise<RenderDocumentResult>;
418

419
interface RenderDocumentArgs {
420
  id?: string | number;
421
  collection?: string;
422
  global?: string;
423
  locale?: string;
424
  fallbackLocale?: string;
425
  depth?: number;
426
  overrides?: Record<string, unknown>;
427
}
428

429
interface RenderDocumentResult {
430
  doc: Record<string, unknown>;
431
  permissions: Record<string, unknown>;
432
}
433
```
434

435
### ClientFunctionProvider
436

437
Client-side function registry provider.
438

439
```typescript { .api }
440
interface ClientFunctionProviderProps {
441
  children: React.ReactNode;
442
}
443

444
function ClientFunctionProvider(props: ClientFunctionProviderProps): JSX.Element;
445

446
function useClientFunctions(): ClientFunctionsContext;
447
function useAddClientFunction(): (name: string, func: Function) => void;
448

449
interface ClientFunctionsContext {
450
  [key: string]: Function;
451
}
452
```
453

454
### ActionsProvider
455

456
Global actions registry provider.
457

458
```typescript { .api }
459
interface ActionsProviderProps {
460
  children: React.ReactNode;
461
}
462

463
function ActionsProvider(props: ActionsProviderProps): JSX.Element;
464

465
function useActions(): ActionsContext;
466

467
interface ActionsContext {
468
  setViewActions: (actions: ViewAction[]) => void;
469
  getViewActions: () => ViewAction[];
470
}
471
```
472

473
### LivePreviewProvider
474

475
Live preview functionality provider.
476

477
```typescript { .api }
478
interface LivePreviewProviderProps {
479
  children: React.ReactNode;
480
}
481

482
function LivePreviewProvider(props: LivePreviewProviderProps): JSX.Element;
483
```
484

485
### SearchParamsProvider
486

487
URL search parameters provider.
488

489
```typescript { .api }
490
interface SearchParamsProviderProps {
491
  children: React.ReactNode;
492
  searchParams: Record<string, string>;
493
}
494

495
function SearchParamsProvider(props: SearchParamsProviderProps): JSX.Element;
496

497
function useSearchParams(): SearchParamsContext;
498

499
interface SearchParamsContext {
500
  searchParams: Record<string, string>;
501
  replace: (params: Record<string, string>) => void;
502
  push: (params: Record<string, string>) => void;
503
}
504
```
505

506
## Upload and File Providers
507

508
### UploadHandlersProvider
509

510
Upload handling functions provider.
511

512
```typescript { .api }
513
interface UploadHandlersProviderProps {
514
  children: React.ReactNode;
515
}
516

517
function UploadHandlersProvider(props: UploadHandlersProviderProps): JSX.Element;
518

519
function useUploadHandlers(): UploadHandlersContext;
520

521
interface UploadHandlersContext {
522
  upload: (files: File[]) => Promise<UploadResult[]>;
523
  replace: (id: string, file: File) => Promise<UploadResult>;
524
  remove: (id: string) => Promise<void>;
525
}
526
```
527

528
### UploadEditsProvider
529

530
Upload editing state provider.
531

532
```typescript { .api }
533
interface UploadEditsProviderProps {
534
  children: React.ReactNode;
535
}
536

537
function UploadEditsProvider(props: UploadEditsProviderProps): JSX.Element;
538

539
function useUploadEdits(): UploadEditsContext;
540

541
interface UploadEditsContext {
542
  edits: UploadEdit[];
543
  addEdit: (edit: UploadEdit) => void;
544
  removeEdit: (id: string) => void;
545
  applyEdits: () => Promise<void>;
546
}
547
```
548

549
## Provider Composition Example
550

551
```typescript
552
import {
553
  RootProvider,
554
  ConfigProvider,
555
  AuthProvider,
556
  ThemeProvider,
557
  TranslationProvider,
558
  WindowInfoProvider
559
} from '@payloadcms/ui';
560

561
function AdminApp({ config, user, locale = 'en' }) {
562
  return (
563
    <RootProvider>
564
      <ConfigProvider config={config}>
565
        <AuthProvider user={user}>
566
          <ThemeProvider theme="auto">
567
            <TranslationProvider>
568
              <WindowInfoProvider>
569
                <LocaleProvider locale={locale}>
570
                  <YourAdminInterface />
571
                </LocaleProvider>
572
              </WindowInfoProvider>
573
            </TranslationProvider>
574
          </ThemeProvider>
575
        </AuthProvider>
576
      </ConfigProvider>
577
    </RootProvider>
578
  );
579
}
580
```
581

582
## Types
583

584
```typescript { .api }
585
interface ClientConfig {
586
  routes: {
587
    admin: string;
588
    api: string;
589
  };
590
  collections: CollectionConfig[];
591
  globals: GlobalConfig[];
592
  localization?: LocalizationConfig;
593
  admin: AdminConfig;
594
}
595

596
interface ClientUser {
597
  id: string;
598
  email?: string;
599
  [key: string]: unknown;
600
}
601

602
interface SanitizedPermissions {
603
  collections: Record<string, CollectionPermission>;
604
  globals: Record<string, GlobalPermission>;
605
  canAccessAdmin: boolean;
606
}
607

608
interface CollectionPermission {
609
  create: boolean;
610
  read: boolean;
611
  update: boolean;
612
  delete: boolean;
613
}
614

615
interface GlobalPermission {
616
  read: boolean;
617
  update: boolean;
618
}
619

620
interface Theme {
621
  name: string;
622
  colors: Record<string, string>;
623
  breakpoints: Record<string, string>;
624
}
625

626
interface EntityConfig {
627
  slug: string;
628
  labels: {
629
    singular: string;
630
    plural: string;
631
  };
632
  fields: FieldConfig[];
633
}
634

635
interface ListResult {
636
  docs: Record<string, unknown>[];
637
  totalDocs: number;
638
  totalPages: number;
639
  page: number;
640
  limit: number;
641
  hasNextPage: boolean;
642
  hasPrevPage: boolean;
643
}
644

645
interface ListQuery {
646
  where?: Record<string, unknown>;
647
  sort?: string;
648
  limit?: number;
649
  page?: number;
650
}
651

652
interface ViewAction {
653
  id: string;
654
  label: string;
655
  handler: () => void;
656
}
657

658
interface UploadResult {
659
  id: string;
660
  filename: string;
661
  mimeType: string;
662
  filesize: number;
663
}
664

665
interface UploadEdit {
666
  id: string;
667
  type: 'crop' | 'resize' | 'rotate';
668
  params: Record<string, unknown>;
669
}
670
```