Payload Advanced Fields

A collection of enhanced field types for Payload CMS.

Table of Contents

• Features
• Installation
• Field Types
• Usage Examples
• Architecture
• License

Features

• Color Picker Field - 10 different color picker styles with preset colors
• Code Editor Field - Syntax-highlighted code editing with CodeMirror
• Link Field - Internal/external link management with validation
• Phone Field - Canonical phone data with country selector, extension input, validation, and custom formatting
• Message Field - Localized, tone-aware admin notices that do not store a value
• Data Table Field - A spreadsheet-style table built with TanStack Table, Radix menus, CSV import/export, formulas, sticky rows, reordering, row virtualization, and hard limits of 250 rows and 50 columns
• Optimized Bundling - Each field is independently bundled for minimal bloat
• Tree-shakeable - Import only what you need
• Full TypeScript Support - Complete type definitions included
• Localization Ready - Support for multi-language content

Installation

npm install @studio123/payload-advanced-fields

Field Types

| Field | Docs | Import | Summary | | ---------- | ----------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Color | Documentation | @studio123/payload-advanced-fields/color | Color picker field with swatches and multiple react-color styles. | | Code | Documentation | @studio123/payload-advanced-fields/code | Syntax-highlighted code editor powered by CodeMirror. | | Link | Documentation | @studio123/payload-advanced-fields/link | Internal/external link field with plugin-level collection config. | | Phone | Documentation | @studio123/payload-advanced-fields/phone | Canonical phone data field with country selector, extension input, validation, and custom formatting. | | Message | Documentation | @studio123/payload-advanced-fields/message | Localized admin notice with info, success, warning, and error tones; stores no value. | | Data Table | Documentation | @studio123/payload-advanced-fields/data-table | Editable JSON table with sorting, resizing, and row/column editing; limited to 250 rows and 50 columns. |

Usage Examples

Data Table fields

import { dataTableField } from '@studio123/payload-advanced-fields/data-table';

const fields = [
  dataTableField({ name: 'specifications' }),
  dataTableField({
    name: 'priceList',
    rows: { initial: 5 },
    columns: { initial: 4 },
    formulas: { enabled: true },
    apiResponse: { computeFormulas: true, includeIds: true },
  }),
];

See the Data Table field guide for the value contract and configuration. This package currently pins Payload and @payloadcms/ui to 4.0.0-canary.37.

Data Table dimensions default to three initial rows and columns, with maximums of 250 rows and 50 columns. Lower row and column limits can be configured with rows.max and columns.max. Use a collection when a dataset exceeds these limits. API response IDs and computed formula values are opt-in through apiResponse; stored values remain compact by default.

Complete Global Configuration with Multiple Fields

import { GlobalConfig } from 'payload';
import { colorField } from '@studio123/payload-advanced-fields/color';
import { codeField } from '@studio123/payload-advanced-fields/code';
import { linkField } from '@studio123/payload-advanced-fields/link';
import { phoneField } from '@studio123/payload-advanced-fields/phone';

export const SiteSettings: GlobalConfig = {
  slug: 'site-settings',
  fields: [
    {
      type: 'tabs',
      tabs: [
        {
          name: 'branding',
          label: 'Branding',
          fields: [
            colorField({
              name: 'primaryColor',
              label: 'Primary Color',
              pickerType: 'sketch',
              required: true,
              presetColors: [
                { hex: '#000000', slug: 'black' },
                { hex: '#FFFFFF', slug: 'white' },
              ],
            }),
            colorField({
              name: 'secondaryColor',
              label: 'Secondary Color',
              pickerType: 'compact',
            }),
          ],
        },
        {
          name: 'content',
          label: 'Content',
          fields: [
            codeField({
              name: 'customCSS',
              label: 'Custom CSS',
              language: 'css',
              height: 400,
            }),
            phoneField({
              name: 'supportPhone',
              label: 'Support Phone',
              defaultCountry: 'US',
              admin: {
                placeholder: 'Enter a support phone number',
                width: '50%',
              },
              countries: {
                enabled: true,
                enabledCountries: ['US', 'CA'],
              },
              extension: {
                enabled: true,
              },
            }),
            linkField({
              name: 'privacyPolicy',
              label: 'Privacy Policy Link',
              collectionSlugs: ['pages'],
            }),
          ],
        },
      ],
    },
  ],
};

Collection with Mix of Field Types

import { CollectionConfig } from 'payload';
import { colorField } from '@studio123/payload-advanced-fields/color';
import { linkField } from '@studio123/payload-advanced-fields/link';
import { phoneField } from '@studio123/payload-advanced-fields/phone';

export const Products: CollectionConfig = {
  slug: 'products',
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'description',
      type: 'textarea',
    },
    colorField({
      name: 'tagColor',
      label: 'Tag Color',
      pickerType: 'block',
      presetColors: [
        { hex: '#FF6B6B', label: 'Hot Pink', slug: 'hot-pink' },
        { hex: '#4ECDC4', label: 'Teal', slug: 'teal' },
        { hex: '#FFE66D', label: 'Golden', slug: 'golden' },
      ],
    }),
    linkField({
      name: 'externalLink',
      label: 'Product Link',
      description: 'Link to the product page or storefront',
    }),
    phoneField({
      name: 'supportPhone',
      label: 'Support Phone',
      defaultCountry: 'US',
      admin: {
        width: '50%',
      },
      countries: {
        enabled: false,
      },
    }),
  ],
};

Architecture

Entry Points

Each field has its own entry point to minimize bundle size. Import only what you need:

// Import server-side field factory
import { colorField } from '@studio123/payload-advanced-fields/color';

// Import client-side component (bundled with dependencies)
import { ColorField } from '@studio123/payload-advanced-fields/color/client';

Bundling Strategy

• Color Field - Bundled with esbuild (includes @uiw/react-color and dependencies)
• Code Field - Compiled with TypeScript (uses external @codemirror)
• Link Field - Compiled with TypeScript (minimal dependencies)
• Phone Field - Compiled with TypeScript and powered by libphonenumber-js
• Message Field - Compiled with TypeScript and rendered entirely in the admin UI
• Data Table Field - Compiled with TypeScript, with a separate client entry point and packaged CSS; no additional runtime dependency

This ensures users only pay for what they use - if you only use ColorField, you don't load CodeMirror.

Color Format Support

The ColorField supports multiple input formats that are automatically normalized:

• Hex colors - #FF0000, #F00
• Hex with alpha - #FF0000AA, #F00A
• RGB/RGBA - rgb(255, 0, 0), rgba(255, 0, 0, 0.5)
• CSS color names - red, transparent, blue, etc.
• Existing ColorValue objects - Full color data preserved

All formats are automatically converted to internal HSV representation for pickers, then stored with complete RGB, HSL, and HSV data.

License

This project is licensed under the MIT License. See LICENSE for details.

For information about bundled dependencies and their licenses, see LICENSES.md.