CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-payloadcms--ui

UI components library for Payload CMS providing React components, hooks, forms, and styling for building admin interfaces and extensible UI elements.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

components.mddocs/

UI Components

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

Core Elements

Button

Flexible button component with icon support and multiple appearances.

interface ButtonProps {
  children?: React.ReactNode;
  type?: 'button' | 'submit' | 'reset';
  appearance?: 'primary' | 'secondary' | 'danger' | 'success' | 'default';
  size?: 'small' | 'medium' | 'large';
  icon?: React.ReactNode;
  iconStyle?: 'with-label' | 'without-label';
  disabled?: boolean;
  onClick?: (event: React.MouseEvent) => void;
  className?: string;
  id?: string;
  round?: boolean;
}

function Button(props: ButtonProps): JSX.Element;

Usage example:

import { Button, PlusIcon } from '@payloadcms/ui';

function AddButton() {
  return (
    <Button 
      appearance="primary" 
      icon={<PlusIcon />}
      onClick={() => handleAdd()}
    >
      Add Item
    </Button>
  );
}

Card

Container card component for grouping related content.

interface CardProps {
  children: React.ReactNode;
  className?: string;
  id?: string;
  buttonAriaLabel?: string;
  onClick?: () => void;
  actions?: React.ReactNode;
}

function Card(props: CardProps): JSX.Element;

Modal

Modal dialog component with overlay and focus management.

interface ModalProps {
  children: React.ReactNode;
  className?: string;
  slug?: string;
  size?: 'small' | 'medium' | 'large' | 'full';
}

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

function useModal(): {
  openModal: (slug: string) => void;
  closeModal: (slug: string) => void;
  closeAllModals: () => void;
  currentModal: string | null;
};

Tooltip

Tooltip overlay component for providing contextual help.

interface TooltipProps {
  children: React.ReactNode;
  className?: string;
  show?: boolean;
  delay?: number;
  position?: 'top' | 'bottom' | 'left' | 'right';
}

function Tooltip(props: TooltipProps): JSX.Element;

Banner

Alert and notification banner component.

interface BannerProps {
  children: React.ReactNode;
  type?: 'success' | 'error' | 'warning' | 'info';
  icon?: React.ReactNode;
  className?: string;
}

function Banner(props: BannerProps): JSX.Element;

Popup

Dropdown popup component for contextual actions.

interface PopupProps {
  children: React.ReactNode;
  className?: string;
  button?: React.ReactNode;
  buttonType?: 'default' | 'custom';
  horizontalAlign?: 'left' | 'center' | 'right';
  verticalAlign?: 'top' | 'bottom';
  size?: 'small' | 'medium' | 'large' | 'fit-content';
  color?: 'light' | 'dark';
  initActive?: boolean;
  onToggleOpen?: (active: boolean) => void;
}

function Popup(props: PopupProps): JSX.Element;

Navigation & Layout

AppHeader

Main application header component.

interface AppHeaderProps {
  className?: string;
  children?: React.ReactNode;
}

function AppHeader(props: AppHeaderProps): JSX.Element;

Gutter

Layout spacing component for consistent gutters.

interface GutterProps {
  children: React.ReactNode;
  className?: string;
  left?: boolean;
  right?: boolean;
}

function Gutter(props: GutterProps): JSX.Element;

Collapsible

Expandable and collapsible container component.

interface CollapsibleProps {
  children: React.ReactNode;
  className?: string;
  header?: React.ReactNode;
  initCollapsed?: boolean;
  onToggle?: (collapsed: boolean) => void;
}

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

function useCollapsible(): {
  collapse: (id: string) => void;
  expand: (id: string) => void;
  toggle: (id: string) => void;
  isCollapsed: (id: string) => boolean;
};

Hamburger

Hamburger menu icon component.

interface HamburgerProps {
  isActive?: boolean;
  className?: string;
  onClick?: () => void;
}

function Hamburger(props: HamburgerProps): JSX.Element;

NavToggler

Navigation toggle button component.

interface NavTogglerProps {
  className?: string;
  children?: React.ReactNode;
}

function NavToggler(props: NavTogglerProps): JSX.Element;

Data Display

Table

Data table component with sorting and pagination support.

interface TableProps {
  columns: Column[];
  data: Record<string, unknown>[];
  className?: string;
  appearance?: 'condensed' | 'default';
}

interface Column {
  accessor: string;
  components?: {
    Heading?: React.ComponentType<any>;
    renderCell?: (props: CellProps) => JSX.Element;
  };
  active?: boolean;
  label?: string;
  name?: string;
}

interface CellProps {
  field: Column;
  colIndex: number;
  rowData: Record<string, unknown>;
  cellData: unknown;
}

function Table(props: TableProps): JSX.Element;

DefaultCell

Default table cell renderer component.

interface DefaultCellProps {
  field: Column;
  colIndex: number;
  rowData: Record<string, unknown>;
  cellData: unknown;
}

function DefaultCell(props: DefaultCellProps): JSX.Element;

Pagination

Table and list pagination component.

interface PaginationProps {
  limit: number;
  totalPages: number;
  page: number;
  hasPrevPage: boolean;
  hasNextPage: boolean;
  prevPage?: number;
  nextPage?: number;
  pagingCounter: number;
  totalDocs: number;
  onChange?: (page: number) => void;
}

function Pagination(props: PaginationProps): JSX.Element;

PerPage

Items per page selector component.

interface PerPageProps {
  limit: number;
  limits: number[];
  modifySearchParams?: boolean;
  onChange?: (limit: number) => void;
}

function PerPage(props: PerPageProps): JSX.Element;

ListControls

List view controls for search and filtering.

interface ListControlsProps {
  children?: React.ReactNode;
  className?: string;
}

function ListControls(props: ListControlsProps): JSX.Element;

Form Controls

ReactSelect / Select

Enhanced select component based on react-select.

interface ReactSelectProps {
  value?: Option | Option[];
  options: Option[];
  onChange?: (value: Option | Option[] | null) => void;
  onInputChange?: (value: string) => void;
  placeholder?: string;
  isDisabled?: boolean;
  isMulti?: boolean;
  isClearable?: boolean;
  isSearchable?: boolean;
  filterOption?: (option: Option, inputValue: string) => boolean;
  className?: string;
}

interface Option {
  label: string;
  value: string | number;
  disabled?: boolean;
}

function ReactSelect(props: ReactSelectProps): JSX.Element;
const Select = ReactSelect; // Alias

DatePicker

Date and time selection component.

interface DatePickerProps {
  value?: Date;
  onChange?: (date: Date | null) => void;
  displayFormat?: string;
  pickerAppearance?: 'default' | 'dayOnly' | 'timeOnly' | 'dayAndTime';
  placeholder?: string;
  readOnly?: boolean;
  showTimeSelect?: boolean;
  timeFormat?: string;
  timeIntervals?: number;
  minDate?: Date;
  maxDate?: Date;
}

function DatePicker(props: DatePickerProps): JSX.Element;

SearchFilter

Search input component with filtering capabilities.

interface SearchFilterProps {
  fieldName?: string;
  fieldLabel?: string;
  modifySearchQuery?: boolean;
  onChange?: (value: string) => void;
  placeholder?: string;
  handleChange?: (value: string) => void;
}

function SearchFilter(props: SearchFilterProps): JSX.Element;

PillSelector

Pill-based selection component for multiple choices.

interface PillSelectorProps {
  selected?: SelectablePill[];
  pills: SelectablePill[];
  onSelect?: (pill: SelectablePill) => void;
  onDeselect?: (pill: SelectablePill) => void;
  className?: string;
}

interface SelectablePill {
  label: string;
  value: string;
  selected?: boolean;
}

function PillSelector(props: PillSelectorProps): JSX.Element;

Document Management

DocumentControls

Document action controls component.

interface DocumentControlsProps {
  collection?: string;
  global?: string;
  id?: string | number;
  data?: Record<string, unknown>;
  hasPublishPermission?: boolean;
  hasSavePermission?: boolean;
  apiURL?: string;
  action?: string;
  isEditing?: boolean;
}

function DocumentControls(props: DocumentControlsProps): JSX.Element;

DocumentFields

Component for rendering document fields.

interface DocumentFieldsProps {
  BeforeFields?: React.ComponentType<any>;
  AfterFields?: React.ComponentType<any>;
  fields: FieldConfig[];
  readOnly?: boolean;
  permissions?: Record<string, unknown>;
}

function DocumentFields(props: DocumentFieldsProps): JSX.Element;

DocumentDrawer

Slide-out document editor drawer.

interface DocumentDrawerProps {
  slug?: string;
  children?: React.ReactNode;
  className?: string;
}

function useDocumentDrawer(): UseDocumentDrawer;

interface UseDocumentDrawer {
  openDrawer: (slug: string) => void;
  closeDrawer: (slug: string) => void;
  toggleDrawer: (slug: string) => void;
  isDrawerOpen: (slug: string) => boolean;
}

interface DocumentTogglerProps {
  children: React.ReactNode;
  className?: string;
  disabled?: boolean;
  drawerSlug: string;
}

DocumentLocked

Locked document indicator component.

interface DocumentLockedProps {
  className?: string;
  user?: {
    id: string;
    email: string;
  };
}

function DocumentLocked(props: DocumentLockedProps): JSX.Element;

DocumentTakeOver

Document takeover dialog component.

interface DocumentTakeOverProps {
  className?: string;
  onTakeOver?: () => void;
}

function DocumentTakeOver(props: DocumentTakeOverProps): JSX.Element;

File and Upload Management

Upload

File upload component with drag-and-drop support.

interface UploadProps {
  className?: string;
  relationTo: string;
  value?: UploadValue;
  onChange?: (value: UploadValue | null) => void;
  disabled?: boolean;
}

interface UploadValue {
  id: string;
  filename: string;
  mimeType: string;
  filesize: number;
  width?: number;
  height?: number;
  url?: string;
}

function Upload(props: UploadProps): JSX.Element;

Dropzone

Drag-and-drop upload area component.

interface DropzoneProps {
  className?: string;
  accept?: string[];
  maxFiles?: number;
  onDrop?: (files: File[]) => void;
  disabled?: boolean;
  children?: React.ReactNode;
}

function Dropzone(props: DropzoneProps): JSX.Element;

Thumbnail

Image thumbnail display component.

interface ThumbnailProps {
  className?: string;
  src?: string;
  alt?: string;
  size?: 'small' | 'medium' | 'large';
  fit?: 'crop' | 'contain' | 'cover';
}

function Thumbnail(props: ThumbnailProps): JSX.Element;

FileDetails

File information display component.

interface FileDetailsProps {
  file: {
    filename: string;
    mimeType: string;
    filesize: number;
    width?: number;
    height?: number;
  };
  className?: string;
}

function FileDetails(props: FileDetailsProps): JSX.Element;

PreviewSizes

Image size previews component.

interface PreviewSizesProps {
  sizes?: ImageSize[];
  className?: string;
}

interface ImageSize {
  name: string;
  width: number;
  height: number;
  url: string;
}

function PreviewSizes(props: PreviewSizesProps): JSX.Element;

Action Components

SaveButton

Document save button component.

interface SaveButtonProps {
  className?: string;
  disabled?: boolean;
  processing?: boolean;
}

function SaveButton(props: SaveButtonProps): JSX.Element;

SaveDraftButton

Save draft button component.

interface SaveDraftButtonProps {
  className?: string;
  disabled?: boolean;
  processing?: boolean;
}

function SaveDraftButton(props: SaveDraftButtonProps): JSX.Element;

PublishButton

Publish document button component.

interface PublishButtonProps {
  className?: string;
  disabled?: boolean;
  processing?: boolean;
}

function PublishButton(props: PublishButtonProps): JSX.Element;

DeleteMany

Bulk delete action component.

interface DeleteManyProps {
  className?: string;
  collection: string;
  resetParams?: boolean;
}

function DeleteMany(props: DeleteManyProps): JSX.Element;

PublishMany

Bulk publish action component.

interface PublishManyProps {
  className?: string;
  collection: string;
  resetParams?: boolean;
}

function PublishMany(props: PublishManyProps): JSX.Element;

EditMany

Bulk edit action component.

interface EditManyProps {
  className?: string;
  collection: string;
  resetParams?: boolean;
}

function EditMany(props: EditManyProps): JSX.Element;

Utility Components

Pill

Status and tag pill component.

interface PillProps {
  children: React.ReactNode;
  className?: string;
  backgroundColor?: string;
  color?: string;
  to?: string;
  onClick?: () => void;
}

function Pill(props: PillProps): JSX.Element;

ErrorPill

Error status indicator component.

interface ErrorPillProps {
  className?: string;
  message?: string;
  withMessage?: boolean;
}

function ErrorPill(props: ErrorPillProps): JSX.Element;

Loading Components

Loading state indicators and overlays.

function LoadingOverlay(props: { className?: string }): JSX.Element;
function LoadingOverlayToggle(props: { className?: string; show?: boolean }): JSX.Element;
function FormLoadingOverlayToggle(props: { className?: string }): JSX.Element;

ShimmerEffect

Loading shimmer animation component.

interface ShimmerEffectProps {
  className?: string;
  height?: number;
  width?: number;
}

function ShimmerEffect(props: ShimmerEffectProps): JSX.Element;
function StaggeredShimmers(props: { className?: string; count?: number }): JSX.Element;

AnimateHeight

Height animation wrapper component.

interface AnimateHeightProps {
  children: React.ReactNode;
  className?: string;
  height?: number | 'auto';
  duration?: number;
}

function AnimateHeight(props: AnimateHeightProps): JSX.Element;

Toast Notifications

Toast notification system using Sonner.

interface ToastOptions {
  description?: string;
  action?: {
    label: string;
    onClick: () => void;
  };
  duration?: number;
  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
}

const toast: {
  success: (message: string, options?: ToastOptions) => void;
  error: (message: string, options?: ToastOptions) => void;
  warning: (message: string, options?: ToastOptions) => void;
  info: (message: string, options?: ToastOptions) => void;
  loading: (message: string, options?: ToastOptions) => void;
  dismiss: (id?: string) => void;
};

Usage example:

import { toast } from '@payloadcms/ui';

function handleSave() {
  const loadingId = toast.loading('Saving document...');
  
  try {
    await saveDocument();
    toast.dismiss(loadingId);
    toast.success('Document saved successfully!');
  } catch (error) {
    toast.dismiss(loadingId);
    toast.error('Failed to save document');
  }
}

View Components

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

DefaultListView

Standard collection list view component.

interface DefaultListViewProps {
  collection: string;
  className?: string;
}

function DefaultListView(props: DefaultListViewProps): JSX.Element;

DefaultEditView

Standard document editor view component.

interface DefaultEditViewProps {
  collection?: string;
  global?: string;
  id?: string | number;
  className?: string;
}

function DefaultEditView(props: DefaultEditViewProps): JSX.Element;

SetDocumentStepNav

Document navigation steps component for multi-step editing.

interface SetDocumentStepNavProps {
  steps: StepNavItem[];
  currentStep: number;
}

interface StepNavItem {
  label: string;
  path: string;
  completed?: boolean;
}

function SetDocumentStepNav(props: SetDocumentStepNavProps): JSX.Element;

SetDocumentTitle

Document title management component.

interface SetDocumentTitleProps {
  title?: string;
  fallback?: string;
}

function SetDocumentTitle(props: SetDocumentTitleProps): JSX.Element;

ListHeader / CollectionListHeader

List view header with controls and actions.

interface ListHeaderProps {
  collection: string;
  hasCreatePermission?: boolean;
  newDocumentURL?: string;
}

function ListHeader(props: ListHeaderProps): JSX.Element;
const CollectionListHeader = ListHeader; // Alias

GroupByHeader

Grouping header controls for list views.

interface GroupByHeaderProps {
  collection: string;
  groupBy?: string;
  onGroupByChange?: (field: string) => void;
}

function GroupByHeader(props: GroupByHeaderProps): JSX.Element;

ListSelection

Multi-select controls for list views.

interface ListSelectionProps {
  children?: React.ReactNode;
}

function ListSelection(props: ListSelectionProps): JSX.Element;

Graphics Components

Brand graphics and visual elements for Payload admin interfaces.

PayloadIcon

Payload logo icon component.

interface PayloadIconProps {
  className?: string;
  size?: number | string;
  style?: React.CSSProperties;
}

function PayloadIcon(props: PayloadIconProps): JSX.Element;

PayloadLogo

Full Payload logo component.

interface PayloadLogoProps {
  className?: string;
  size?: number | string;
  style?: React.CSSProperties;
}

function PayloadLogo(props: PayloadLogoProps): JSX.Element;

Account

User account graphic component.

interface AccountProps {
  className?: string;
  size?: number | string;
}

function Account(props: AccountProps): JSX.Element;

DefaultBlockImage

Default block placeholder image.

interface DefaultBlockImageProps {
  className?: string;
}

function DefaultBlockImage(props: DefaultBlockImageProps): JSX.Element;

File

File representation graphic component.

interface FileProps {
  className?: string;
  size?: number | string;
}

function File(props: FileProps): JSX.Element;

Static Assets

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

const payloadFavicon: string; // SVG favicon
const payloadFaviconDark: string; // Dark mode PNG favicon  
const payloadFaviconLight: string; // Light mode PNG favicon
const staticOGImage: string; // Open Graph image PNG

Usage example:

import { 
  payloadFavicon, 
  payloadFaviconDark, 
  staticOGImage 
} from '@payloadcms/ui/assets';

function AppHead() {
  return (
    <head>
      <link rel="icon" href={payloadFavicon} />
      <meta property="og:image" content={staticOGImage} />
    </head>
  );
}

Types

interface ImageSize {
  name: string;
  width: number;
  height: number;
  url: string;
}

interface FieldConfig {
  type: string;
  name: string;
  label?: string;
  required?: boolean;
  admin?: Record<string, unknown>;
}

interface StepNavItem {
  label: string;
  path: string;
  completed?: boolean;
}

Install with Tessl CLI

npx tessl i tessl/npm-payloadcms--ui

docs

components.md

fields.md

forms.md

hooks.md

icons.md

index.md

providers.md

utilities.md

tile.json