or run

npx @tessl/cli init
Log in

Version

Files

tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@payloadcms/ui@3.54.x

To install, run

npx @tessl/cli install tessl/npm-payloadcms--ui@3.54.0

index.mddocs/

@payloadcms/ui

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.

Package Information

  • Package Name: @payloadcms/ui
  • Package Type: npm
  • Language: TypeScript/React
  • Installation: npm install @payloadcms/ui
  • Peer Dependencies: React 19+, Next.js 15+, Payload CMS

Core Imports

Main Client-Side API

import { 
  Button, 
  Table, 
  Form, 
  useField, 
  useAuth, 
  TextField 
} from '@payloadcms/ui';

Shared Utilities (Server/Client Compatible)

import { 
  buildFormState, 
  buildTableState, 
  parseSearchParams 
} from '@payloadcms/ui/shared';

React Server Components

import { 
  DefaultListView, 
  DefaultEditView 
} from '@payloadcms/ui/rsc';

Individual Elements

import { Button } from '@payloadcms/ui/elements/Button';
import { PlusIcon } from '@payloadcms/ui/icons/Plus';
import { useField } from '@payloadcms/ui/forms/useField';

Static Assets

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

Basic Usage

Setting Up Providers

import { 
  RootProvider, 
  AuthProvider, 
  ConfigProvider, 
  ThemeProvider 
} from '@payloadcms/ui';

function AdminApp({ config, user }) {
  return (
    <RootProvider>
      <ConfigProvider config={config}>
        <AuthProvider user={user}>
          <ThemeProvider theme="auto">
            <YourAdminInterface />
          </ThemeProvider>
        </AuthProvider>
      </ConfigProvider>
    </RootProvider>
  );
}

Form Management

import { Form, TextField, useForm } from '@payloadcms/ui';

function DocumentEditor() {
  const { submit, getData } = useForm();
  
  const handleSubmit = async () => {
    const formData = getData();
    await submit();
  };

  return (
    <Form onSubmit={handleSubmit}>
      <TextField 
        path="title" 
        label="Document Title"
        required 
      />
      <TextField 
        path="content" 
        label="Content"
      />
    </Form>
  );
}

Field Hooks

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

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

  return (
    <div>
      <input
        value={value || ''}
        onChange={(e) => setValue(e.target.value)}
      />
      {showError && <span>{errorMessage}</span>}
    </div>
  );
}

Architecture

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

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

Capabilities

Form System and Field Components

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

function useField<TValue>(options?: {
  path?: string;
  validate?: (value: TValue) => string | true;
  disableFormData?: boolean;
}): FieldType<TValue>;

interface FieldType<TValue> {
  value: TValue;
  setValue: (value: TValue) => void;
  showError: boolean;
  errorMessage?: string;
  valid: boolean;
  disabled: boolean;
}

Form System and Utilities

Field Components

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

interface TextFieldProps {
  path: string;
  label?: string;
  placeholder?: string;
  required?: boolean;
  readOnly?: boolean;
  validate?: (value: string) => string | true;
}

function TextField(props: TextFieldProps): JSX.Element;
function SelectField(props: SelectFieldProps): JSX.Element;
function RichTextField(props: RichTextFieldProps): JSX.Element;

Field Components

React Hooks

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

function usePayloadAPI<T>(url: string, options?: {
  initialData?: T;
  initialParams?: Record<string, unknown>;
}): [{
  data: T;
  isError: boolean;
  isLoading: boolean;
}, {
  setParams: (params: Record<string, unknown>) => void;
}];

function useAuth<T = any>(): AuthContext<T>;
function useDebounce<T>(value: T, delay: number): T;

React Hooks

UI Components and Elements

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

interface ButtonProps {
  children?: React.ReactNode;
  type?: 'button' | 'submit' | 'reset';
  appearance?: 'primary' | 'secondary' | 'danger' | 'success';
  size?: 'small' | 'medium' | 'large';
  icon?: React.ReactNode;
  disabled?: boolean;
  onClick?: () => void;
}

function Button(props: ButtonProps): JSX.Element;
function Table(props: TableProps): JSX.Element;
function Modal(props: ModalProps): JSX.Element;
function DefaultListView(props: DefaultListViewProps): JSX.Element;
function DefaultEditView(props: DefaultEditViewProps): JSX.Element;
function PayloadIcon(props: PayloadIconProps): JSX.Element;

UI Components

Context Providers

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

interface AuthProviderProps {
  children: React.ReactNode;
  user?: ClientUser;
  permissions?: SanitizedPermissions;
}

function AuthProvider(props: AuthProviderProps): JSX.Element;
function ConfigProvider(props: { config: ClientConfig; children: React.ReactNode }): JSX.Element;
function ThemeProvider(props: { theme: Theme; children: React.ReactNode }): JSX.Element;

Context Providers

Icon Components

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

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

function ChevronIcon(props: IconProps): JSX.Element;
function PlusIcon(props: IconProps): JSX.Element;
function EditIcon(props: IconProps): JSX.Element;

Icon Components

Utilities and Helpers

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

function buildFormState(options: {
  fieldSchema: FieldSchema[];
  data?: Record<string, unknown>;
  operation?: 'create' | 'update';
  locale?: string;
}): FormState;

function parseSearchParams(search: string): Record<string, unknown>;
function formatAdminURL(args: { adminRoute: string; path: string }): string;

Utilities and Helpers

Types

interface ClientUser {
  id: string;
  email?: string;
  [key: string]: unknown;
}

interface ClientConfig {
  routes: {
    admin: string;
    api: string;
  };
  collections: CollectionConfig[];
  globals: GlobalConfig[];
  localization?: LocalizationConfig;
}

interface AuthContext<T = any> {
  user: T | null;
  token?: string;
  permissions?: SanitizedPermissions;
  logOut: () => Promise<void>;
  refreshCookie: () => Promise<void>;
}

interface FormState {
  [path: string]: {
    value: unknown;
    valid: boolean;
    errorMessage?: string;
    disableFormData?: boolean;
  };
}

interface Theme {
  name: string;
  colors: Record<string, string>;
  breakpoints: Record<string, string>;
}

interface Column {
  field: string;
  label: string;
  accessor?: string;
  active?: boolean;
}

type ReactSelectOption = {
  label: string;
  value: string | number;
  disabled?: boolean;
};

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

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.