0
# UI Components
1

2
Comprehensive set of UI components for building admin interfaces including buttons, modals, tables, navigation, data display, and specialized admin functionality.
3

4
## Core Elements
5

6
### Button
7

8
Flexible button component with icon support and multiple appearances.
9

10
```typescript { .api }
11
interface ButtonProps {
12
  children?: React.ReactNode;
13
  type?: 'button' | 'submit' | 'reset';
14
  appearance?: 'primary' | 'secondary' | 'danger' | 'success' | 'default';
15
  size?: 'small' | 'medium' | 'large';
16
  icon?: React.ReactNode;
17
  iconStyle?: 'with-label' | 'without-label';
18
  disabled?: boolean;
19
  onClick?: (event: React.MouseEvent) => void;
20
  className?: string;
21
  id?: string;
22
  round?: boolean;
23
}
24

25
function Button(props: ButtonProps): JSX.Element;
26
```
27

28
Usage example:
29
```typescript
30
import { Button, PlusIcon } from '@payloadcms/ui';
31

32
function AddButton() {
33
  return (
34
    <Button 
35
      appearance="primary" 
36
      icon={<PlusIcon />}
37
      onClick={() => handleAdd()}
38
    >
39
      Add Item
40
    </Button>
41
  );
42
}
43
```
44

45
### Card
46

47
Container card component for grouping related content.
48

49
```typescript { .api }
50
interface CardProps {
51
  children: React.ReactNode;
52
  className?: string;
53
  id?: string;
54
  buttonAriaLabel?: string;
55
  onClick?: () => void;
56
  actions?: React.ReactNode;
57
}
58

59
function Card(props: CardProps): JSX.Element;
60
```
61

62
### Modal
63

64
Modal dialog component with overlay and focus management.
65

66
```typescript { .api }
67
interface ModalProps {
68
  children: React.ReactNode;
69
  className?: string;
70
  slug?: string;
71
  size?: 'small' | 'medium' | 'large' | 'full';
72
}
73

74
function Modal(props: ModalProps): JSX.Element;
75

76
function useModal(): {
77
  openModal: (slug: string) => void;
78
  closeModal: (slug: string) => void;
79
  closeAllModals: () => void;
80
  currentModal: string | null;
81
};
82
```
83

84
### Tooltip
85

86
Tooltip overlay component for providing contextual help.
87

88
```typescript { .api }
89
interface TooltipProps {
90
  children: React.ReactNode;
91
  className?: string;
92
  show?: boolean;
93
  delay?: number;
94
  position?: 'top' | 'bottom' | 'left' | 'right';
95
}
96

97
function Tooltip(props: TooltipProps): JSX.Element;
98
```
99

100
### Banner
101

102
Alert and notification banner component.
103

104
```typescript { .api }
105
interface BannerProps {
106
  children: React.ReactNode;
107
  type?: 'success' | 'error' | 'warning' | 'info';
108
  icon?: React.ReactNode;
109
  className?: string;
110
}
111

112
function Banner(props: BannerProps): JSX.Element;
113
```
114

115
### Popup
116

117
Dropdown popup component for contextual actions.
118

119
```typescript { .api }
120
interface PopupProps {
121
  children: React.ReactNode;
122
  className?: string;
123
  button?: React.ReactNode;
124
  buttonType?: 'default' | 'custom';
125
  horizontalAlign?: 'left' | 'center' | 'right';
126
  verticalAlign?: 'top' | 'bottom';
127
  size?: 'small' | 'medium' | 'large' | 'fit-content';
128
  color?: 'light' | 'dark';
129
  initActive?: boolean;
130
  onToggleOpen?: (active: boolean) => void;
131
}
132

133
function Popup(props: PopupProps): JSX.Element;
134
```
135

136
## Navigation & Layout
137

138
### AppHeader
139

140
Main application header component.
141

142
```typescript { .api }
143
interface AppHeaderProps {
144
  className?: string;
145
  children?: React.ReactNode;
146
}
147

148
function AppHeader(props: AppHeaderProps): JSX.Element;
149
```
150

151
### Gutter
152

153
Layout spacing component for consistent gutters.
154

155
```typescript { .api }
156
interface GutterProps {
157
  children: React.ReactNode;
158
  className?: string;
159
  left?: boolean;
160
  right?: boolean;
161
}
162

163
function Gutter(props: GutterProps): JSX.Element;
164
```
165

166
### Collapsible
167

168
Expandable and collapsible container component.
169

170
```typescript { .api }
171
interface CollapsibleProps {
172
  children: React.ReactNode;
173
  className?: string;
174
  header?: React.ReactNode;
175
  initCollapsed?: boolean;
176
  onToggle?: (collapsed: boolean) => void;
177
}
178

179
function Collapsible(props: CollapsibleProps): JSX.Element;
180

181
function useCollapsible(): {
182
  collapse: (id: string) => void;
183
  expand: (id: string) => void;
184
  toggle: (id: string) => void;
185
  isCollapsed: (id: string) => boolean;
186
};
187
```
188

189
### Hamburger
190

191
Hamburger menu icon component.
192

193
```typescript { .api }
194
interface HamburgerProps {
195
  isActive?: boolean;
196
  className?: string;
197
  onClick?: () => void;
198
}
199

200
function Hamburger(props: HamburgerProps): JSX.Element;
201
```
202

203
### NavToggler
204

205
Navigation toggle button component.
206

207
```typescript { .api }
208
interface NavTogglerProps {
209
  className?: string;
210
  children?: React.ReactNode;
211
}
212

213
function NavToggler(props: NavTogglerProps): JSX.Element;
214
```
215

216
## Data Display
217

218
### Table
219

220
Data table component with sorting and pagination support.
221

222
```typescript { .api }
223
interface TableProps {
224
  columns: Column[];
225
  data: Record<string, unknown>[];
226
  className?: string;
227
  appearance?: 'condensed' | 'default';
228
}
229

230
interface Column {
231
  accessor: string;
232
  components?: {
233
    Heading?: React.ComponentType<any>;
234
    renderCell?: (props: CellProps) => JSX.Element;
235
  };
236
  active?: boolean;
237
  label?: string;
238
  name?: string;
239
}
240

241
interface CellProps {
242
  field: Column;
243
  colIndex: number;
244
  rowData: Record<string, unknown>;
245
  cellData: unknown;
246
}
247

248
function Table(props: TableProps): JSX.Element;
249
```
250

251
### DefaultCell
252

253
Default table cell renderer component.
254

255
```typescript { .api }
256
interface DefaultCellProps {
257
  field: Column;
258
  colIndex: number;
259
  rowData: Record<string, unknown>;
260
  cellData: unknown;
261
}
262

263
function DefaultCell(props: DefaultCellProps): JSX.Element;
264
```
265

266
### Pagination
267

268
Table and list pagination component.
269

270
```typescript { .api }
271
interface PaginationProps {
272
  limit: number;
273
  totalPages: number;
274
  page: number;
275
  hasPrevPage: boolean;
276
  hasNextPage: boolean;
277
  prevPage?: number;
278
  nextPage?: number;
279
  pagingCounter: number;
280
  totalDocs: number;
281
  onChange?: (page: number) => void;
282
}
283

284
function Pagination(props: PaginationProps): JSX.Element;
285
```
286

287
### PerPage
288

289
Items per page selector component.
290

291
```typescript { .api }
292
interface PerPageProps {
293
  limit: number;
294
  limits: number[];
295
  modifySearchParams?: boolean;
296
  onChange?: (limit: number) => void;
297
}
298

299
function PerPage(props: PerPageProps): JSX.Element;
300
```
301

302
### ListControls
303

304
List view controls for search and filtering.
305

306
```typescript { .api }
307
interface ListControlsProps {
308
  children?: React.ReactNode;
309
  className?: string;
310
}
311

312
function ListControls(props: ListControlsProps): JSX.Element;
313
```
314

315
## Form Controls
316

317
### ReactSelect / Select
318

319
Enhanced select component based on react-select.
320

321
```typescript { .api }
322
interface ReactSelectProps {
323
  value?: Option | Option[];
324
  options: Option[];
325
  onChange?: (value: Option | Option[] | null) => void;
326
  onInputChange?: (value: string) => void;
327
  placeholder?: string;
328
  isDisabled?: boolean;
329
  isMulti?: boolean;
330
  isClearable?: boolean;
331
  isSearchable?: boolean;
332
  filterOption?: (option: Option, inputValue: string) => boolean;
333
  className?: string;
334
}
335

336
interface Option {
337
  label: string;
338
  value: string | number;
339
  disabled?: boolean;
340
}
341

342
function ReactSelect(props: ReactSelectProps): JSX.Element;
343
const Select = ReactSelect; // Alias
344
```
345

346
### DatePicker
347

348
Date and time selection component.
349

350
```typescript { .api }
351
interface DatePickerProps {
352
  value?: Date;
353
  onChange?: (date: Date | null) => void;
354
  displayFormat?: string;
355
  pickerAppearance?: 'default' | 'dayOnly' | 'timeOnly' | 'dayAndTime';
356
  placeholder?: string;
357
  readOnly?: boolean;
358
  showTimeSelect?: boolean;
359
  timeFormat?: string;
360
  timeIntervals?: number;
361
  minDate?: Date;
362
  maxDate?: Date;
363
}
364

365
function DatePicker(props: DatePickerProps): JSX.Element;
366
```
367

368
### SearchFilter
369

370
Search input component with filtering capabilities.
371

372
```typescript { .api }
373
interface SearchFilterProps {
374
  fieldName?: string;
375
  fieldLabel?: string;
376
  modifySearchQuery?: boolean;
377
  onChange?: (value: string) => void;
378
  placeholder?: string;
379
  handleChange?: (value: string) => void;
380
}
381

382
function SearchFilter(props: SearchFilterProps): JSX.Element;
383
```
384

385
### PillSelector
386

387
Pill-based selection component for multiple choices.
388

389
```typescript { .api }
390
interface PillSelectorProps {
391
  selected?: SelectablePill[];
392
  pills: SelectablePill[];
393
  onSelect?: (pill: SelectablePill) => void;
394
  onDeselect?: (pill: SelectablePill) => void;
395
  className?: string;
396
}
397

398
interface SelectablePill {
399
  label: string;
400
  value: string;
401
  selected?: boolean;
402
}
403

404
function PillSelector(props: PillSelectorProps): JSX.Element;
405
```
406

407
## Document Management
408

409
### DocumentControls
410

411
Document action controls component.
412

413
```typescript { .api }
414
interface DocumentControlsProps {
415
  collection?: string;
416
  global?: string;
417
  id?: string | number;
418
  data?: Record<string, unknown>;
419
  hasPublishPermission?: boolean;
420
  hasSavePermission?: boolean;
421
  apiURL?: string;
422
  action?: string;
423
  isEditing?: boolean;
424
}
425

426
function DocumentControls(props: DocumentControlsProps): JSX.Element;
427
```
428

429
### DocumentFields
430

431
Component for rendering document fields.
432

433
```typescript { .api }
434
interface DocumentFieldsProps {
435
  BeforeFields?: React.ComponentType<any>;
436
  AfterFields?: React.ComponentType<any>;
437
  fields: FieldConfig[];
438
  readOnly?: boolean;
439
  permissions?: Record<string, unknown>;
440
}
441

442
function DocumentFields(props: DocumentFieldsProps): JSX.Element;
443
```
444

445
### DocumentDrawer
446

447
Slide-out document editor drawer.
448

449
```typescript { .api }
450
interface DocumentDrawerProps {
451
  slug?: string;
452
  children?: React.ReactNode;
453
  className?: string;
454
}
455

456
function useDocumentDrawer(): UseDocumentDrawer;
457

458
interface UseDocumentDrawer {
459
  openDrawer: (slug: string) => void;
460
  closeDrawer: (slug: string) => void;
461
  toggleDrawer: (slug: string) => void;
462
  isDrawerOpen: (slug: string) => boolean;
463
}
464

465
interface DocumentTogglerProps {
466
  children: React.ReactNode;
467
  className?: string;
468
  disabled?: boolean;
469
  drawerSlug: string;
470
}
471
```
472

473
### DocumentLocked
474

475
Locked document indicator component.
476

477
```typescript { .api }
478
interface DocumentLockedProps {
479
  className?: string;
480
  user?: {
481
    id: string;
482
    email: string;
483
  };
484
}
485

486
function DocumentLocked(props: DocumentLockedProps): JSX.Element;
487
```
488

489
### DocumentTakeOver
490

491
Document takeover dialog component.
492

493
```typescript { .api }
494
interface DocumentTakeOverProps {
495
  className?: string;
496
  onTakeOver?: () => void;
497
}
498

499
function DocumentTakeOver(props: DocumentTakeOverProps): JSX.Element;
500
```
501

502
## File and Upload Management
503

504
### Upload
505

506
File upload component with drag-and-drop support.
507

508
```typescript { .api }
509
interface UploadProps {
510
  className?: string;
511
  relationTo: string;
512
  value?: UploadValue;
513
  onChange?: (value: UploadValue | null) => void;
514
  disabled?: boolean;
515
}
516

517
interface UploadValue {
518
  id: string;
519
  filename: string;
520
  mimeType: string;
521
  filesize: number;
522
  width?: number;
523
  height?: number;
524
  url?: string;
525
}
526

527
function Upload(props: UploadProps): JSX.Element;
528
```
529

530
### Dropzone
531

532
Drag-and-drop upload area component.
533

534
```typescript { .api }
535
interface DropzoneProps {
536
  className?: string;
537
  accept?: string[];
538
  maxFiles?: number;
539
  onDrop?: (files: File[]) => void;
540
  disabled?: boolean;
541
  children?: React.ReactNode;
542
}
543

544
function Dropzone(props: DropzoneProps): JSX.Element;
545
```
546

547
### Thumbnail
548

549
Image thumbnail display component.
550

551
```typescript { .api }
552
interface ThumbnailProps {
553
  className?: string;
554
  src?: string;
555
  alt?: string;
556
  size?: 'small' | 'medium' | 'large';
557
  fit?: 'crop' | 'contain' | 'cover';
558
}
559

560
function Thumbnail(props: ThumbnailProps): JSX.Element;
561
```
562

563
### FileDetails
564

565
File information display component.
566

567
```typescript { .api }
568
interface FileDetailsProps {
569
  file: {
570
    filename: string;
571
    mimeType: string;
572
    filesize: number;
573
    width?: number;
574
    height?: number;
575
  };
576
  className?: string;
577
}
578

579
function FileDetails(props: FileDetailsProps): JSX.Element;
580
```
581

582
### PreviewSizes
583

584
Image size previews component.
585

586
```typescript { .api }
587
interface PreviewSizesProps {
588
  sizes?: ImageSize[];
589
  className?: string;
590
}
591

592
interface ImageSize {
593
  name: string;
594
  width: number;
595
  height: number;
596
  url: string;
597
}
598

599
function PreviewSizes(props: PreviewSizesProps): JSX.Element;
600
```
601

602
## Action Components
603

604
### SaveButton
605

606
Document save button component.
607

608
```typescript { .api }
609
interface SaveButtonProps {
610
  className?: string;
611
  disabled?: boolean;
612
  processing?: boolean;
613
}
614

615
function SaveButton(props: SaveButtonProps): JSX.Element;
616
```
617

618
### SaveDraftButton
619

620
Save draft button component.
621

622
```typescript { .api }
623
interface SaveDraftButtonProps {
624
  className?: string;
625
  disabled?: boolean;
626
  processing?: boolean;
627
}
628

629
function SaveDraftButton(props: SaveDraftButtonProps): JSX.Element;
630
```
631

632
### PublishButton
633

634
Publish document button component.
635

636
```typescript { .api }
637
interface PublishButtonProps {
638
  className?: string;
639
  disabled?: boolean;
640
  processing?: boolean;
641
}
642

643
function PublishButton(props: PublishButtonProps): JSX.Element;
644
```
645

646
### DeleteMany
647

648
Bulk delete action component.
649

650
```typescript { .api }
651
interface DeleteManyProps {
652
  className?: string;
653
  collection: string;
654
  resetParams?: boolean;
655
}
656

657
function DeleteMany(props: DeleteManyProps): JSX.Element;
658
```
659

660
### PublishMany
661

662
Bulk publish action component.
663

664
```typescript { .api }
665
interface PublishManyProps {
666
  className?: string;
667
  collection: string;
668
  resetParams?: boolean;
669
}
670

671
function PublishMany(props: PublishManyProps): JSX.Element;
672
```
673

674
### EditMany
675

676
Bulk edit action component.
677

678
```typescript { .api }
679
interface EditManyProps {
680
  className?: string;
681
  collection: string;
682
  resetParams?: boolean;
683
}
684

685
function EditMany(props: EditManyProps): JSX.Element;
686
```
687

688
## Utility Components
689

690
### Pill
691

692
Status and tag pill component.
693

694
```typescript { .api }
695
interface PillProps {
696
  children: React.ReactNode;
697
  className?: string;
698
  backgroundColor?: string;
699
  color?: string;
700
  to?: string;
701
  onClick?: () => void;
702
}
703

704
function Pill(props: PillProps): JSX.Element;
705
```
706

707
### ErrorPill
708

709
Error status indicator component.
710

711
```typescript { .api }
712
interface ErrorPillProps {
713
  className?: string;
714
  message?: string;
715
  withMessage?: boolean;
716
}
717

718
function ErrorPill(props: ErrorPillProps): JSX.Element;
719
```
720

721
### Loading Components
722

723
Loading state indicators and overlays.
724

725
```typescript { .api }
726
function LoadingOverlay(props: { className?: string }): JSX.Element;
727
function LoadingOverlayToggle(props: { className?: string; show?: boolean }): JSX.Element;
728
function FormLoadingOverlayToggle(props: { className?: string }): JSX.Element;
729
```
730

731
### ShimmerEffect
732

733
Loading shimmer animation component.
734

735
```typescript { .api }
736
interface ShimmerEffectProps {
737
  className?: string;
738
  height?: number;
739
  width?: number;
740
}
741

742
function ShimmerEffect(props: ShimmerEffectProps): JSX.Element;
743
function StaggeredShimmers(props: { className?: string; count?: number }): JSX.Element;
744
```
745

746
### AnimateHeight
747

748
Height animation wrapper component.
749

750
```typescript { .api }
751
interface AnimateHeightProps {
752
  children: React.ReactNode;
753
  className?: string;
754
  height?: number | 'auto';
755
  duration?: number;
756
}
757

758
function AnimateHeight(props: AnimateHeightProps): JSX.Element;
759
```
760

761
## Toast Notifications
762

763
Toast notification system using Sonner.
764

765
```typescript { .api }
766
interface ToastOptions {
767
  description?: string;
768
  action?: {
769
    label: string;
770
    onClick: () => void;
771
  };
772
  duration?: number;
773
  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
774
}
775

776
const toast: {
777
  success: (message: string, options?: ToastOptions) => void;
778
  error: (message: string, options?: ToastOptions) => void;
779
  warning: (message: string, options?: ToastOptions) => void;
780
  info: (message: string, options?: ToastOptions) => void;
781
  loading: (message: string, options?: ToastOptions) => void;
782
  dismiss: (id?: string) => void;
783
};
784
```
785

786
Usage example:
787
```typescript
788
import { toast } from '@payloadcms/ui';
789

790
function handleSave() {
791
  const loadingId = toast.loading('Saving document...');
792
  
793
  try {
794
    await saveDocument();
795
    toast.dismiss(loadingId);
796
    toast.success('Document saved successfully!');
797
  } catch (error) {
798
    toast.dismiss(loadingId);
799
    toast.error('Failed to save document');
800
  }
801
}
802
```
803

804
## View Components
805

806
View components for pre-built list and edit interfaces in Payload admin.
807

808
### DefaultListView
809

810
Standard collection list view component.
811

812
```typescript { .api }
813
interface DefaultListViewProps {
814
  collection: string;
815
  className?: string;
816
}
817

818
function DefaultListView(props: DefaultListViewProps): JSX.Element;
819
```
820

821
### DefaultEditView
822

823
Standard document editor view component.
824

825
```typescript { .api }
826
interface DefaultEditViewProps {
827
  collection?: string;
828
  global?: string;
829
  id?: string | number;
830
  className?: string;
831
}
832

833
function DefaultEditView(props: DefaultEditViewProps): JSX.Element;
834
```
835

836
### SetDocumentStepNav
837

838
Document navigation steps component for multi-step editing.
839

840
```typescript { .api }
841
interface SetDocumentStepNavProps {
842
  steps: StepNavItem[];
843
  currentStep: number;
844
}
845

846
interface StepNavItem {
847
  label: string;
848
  path: string;
849
  completed?: boolean;
850
}
851

852
function SetDocumentStepNav(props: SetDocumentStepNavProps): JSX.Element;
853
```
854

855
### SetDocumentTitle
856

857
Document title management component.
858

859
```typescript { .api }
860
interface SetDocumentTitleProps {
861
  title?: string;
862
  fallback?: string;
863
}
864

865
function SetDocumentTitle(props: SetDocumentTitleProps): JSX.Element;
866
```
867

868
### ListHeader / CollectionListHeader
869

870
List view header with controls and actions.
871

872
```typescript { .api }
873
interface ListHeaderProps {
874
  collection: string;
875
  hasCreatePermission?: boolean;
876
  newDocumentURL?: string;
877
}
878

879
function ListHeader(props: ListHeaderProps): JSX.Element;
880
const CollectionListHeader = ListHeader; // Alias
881
```
882

883
### GroupByHeader
884

885
Grouping header controls for list views.
886

887
```typescript { .api }
888
interface GroupByHeaderProps {
889
  collection: string;
890
  groupBy?: string;
891
  onGroupByChange?: (field: string) => void;
892
}
893

894
function GroupByHeader(props: GroupByHeaderProps): JSX.Element;
895
```
896

897
### ListSelection
898

899
Multi-select controls for list views.
900

901
```typescript { .api }
902
interface ListSelectionProps {
903
  children?: React.ReactNode;
904
}
905

906
function ListSelection(props: ListSelectionProps): JSX.Element;
907
```
908

909
## Graphics Components
910

911
Brand graphics and visual elements for Payload admin interfaces.
912

913
### PayloadIcon
914

915
Payload logo icon component.
916

917
```typescript { .api }
918
interface PayloadIconProps {
919
  className?: string;
920
  size?: number | string;
921
  style?: React.CSSProperties;
922
}
923

924
function PayloadIcon(props: PayloadIconProps): JSX.Element;
925
```
926

927
### PayloadLogo
928

929
Full Payload logo component.
930

931
```typescript { .api }
932
interface PayloadLogoProps {
933
  className?: string;
934
  size?: number | string;
935
  style?: React.CSSProperties;
936
}
937

938
function PayloadLogo(props: PayloadLogoProps): JSX.Element;
939
```
940

941
### Account
942

943
User account graphic component.
944

945
```typescript { .api }
946
interface AccountProps {
947
  className?: string;
948
  size?: number | string;
949
}
950

951
function Account(props: AccountProps): JSX.Element;
952
```
953

954
### DefaultBlockImage
955

956
Default block placeholder image.
957

958
```typescript { .api }
959
interface DefaultBlockImageProps {
960
  className?: string;
961
}
962

963
function DefaultBlockImage(props: DefaultBlockImageProps): JSX.Element;
964
```
965

966
### File
967

968
File representation graphic component.
969

970
```typescript { .api }
971
interface FileProps {
972
  className?: string;
973
  size?: number | string;
974
}
975

976
function File(props: FileProps): JSX.Element;
977
```
978

979
## Static Assets
980

981
Static assets available from the `/assets` export for favicons and images.
982

983
```typescript { .api }
984
const payloadFavicon: string; // SVG favicon
985
const payloadFaviconDark: string; // Dark mode PNG favicon  
986
const payloadFaviconLight: string; // Light mode PNG favicon
987
const staticOGImage: string; // Open Graph image PNG
988
```
989

990
Usage example:
991
```typescript
992
import { 
993
  payloadFavicon, 
994
  payloadFaviconDark, 
995
  staticOGImage 
996
} from '@payloadcms/ui/assets';
997

998
function AppHead() {
999
  return (
1000
    <head>
1001
      <link rel="icon" href={payloadFavicon} />
1002
      <meta property="og:image" content={staticOGImage} />
1003
    </head>
1004
  );
1005
}
1006
```
1007

1008
## Types
1009

1010
```typescript { .api }
1011
interface ImageSize {
1012
  name: string;
1013
  width: number;
1014
  height: number;
1015
  url: string;
1016
}
1017

1018
interface FieldConfig {
1019
  type: string;
1020
  name: string;
1021
  label?: string;
1022
  required?: boolean;
1023
  admin?: Record<string, unknown>;
1024
}
1025

1026
interface StepNavItem {
1027
  label: string;
1028
  path: string;
1029
  completed?: boolean;
1030
}
1031
```