Payload CMS: Add a Custom Color Picker Field (Step-by-Step)

I assume you’re using the Payload website template. If not, feel free to adjust the file paths to match your project structure.

1. Create the ColorPicker Component

Create a file at:

📂 src/components/ColorPicker/ColorPicker.tsx

1'use client'
2
3import { useField, TextInput } from '@payloadcms/ui'
4import styles from './ColorPicker.module.css'
5
6const ColorPicker = ({
7  field: { label, required = false },
8  path,
9}: {
10  field: { label: string; required?: boolean }
11  path: string
12}) => {
13  const { value, setValue } = useField<string>({ path })
14
15  return (
16    <div>
17      <label className="field-label">
18        {label} {required && <span className="required">*</span>}
19      </label>
20      <div className={styles.colorPickerRow}>
21        <input type="color" value={value} onChange={(e) => setValue(e.target.value)} />
22        <TextInput
23          label=""
24          path={path}
25          onChange={(e: { target: { value: string } }) => setValue(e.target.value)}
26          value={value}
27        />
28      </div>
29    </div>
30  )
31}
32
33export default ColorPicker
34

2. Create the CSS Module

Create a file for styling:

📂 src/components/ColorPicker/ColorPicker.module.css

1.colorPickerRow {
2  margin-top: 8px;
3  margin-bottom: 8px;
4  display: flex;
5  gap: 16px;
6}
7
8.colorPickerRow .fieldType {
9  width: 100%;
10}
11
12.colorPickerRow input[type='color'] {
13  width: 40px;
14  height: 40px;
15}
16
17.colorPickerRow input[type='text'] {
18  width: 100%;
19}
20

3. Define the Field

Create a new field definition:

📂 src/fields/color.ts

1// src/fields/color.ts
2import type { TextField } from 'payload'
3
4export const COLOR = (overrides?: Omit<TextField, 'type'>): TextField => {
5  const { name = 'color', label = 'Color', admin, ...rest } = overrides ?? {}
6
7  return {
8    type: 'text',
9    name,
10    label,
11    admin: {
12      ...admin,
13      components: {
14        Field: '@/components/ColorPicker/ColorPicker',
15      },
16    },
17    ...rest,
18  } as TextField
19}
20

4. Add the Field to Your Collection

In your collections, add the newly created COLOR field.

1import { Field } from 'payload'
2import { COLOR } from './color'
3
4export const backgroundFields: Field = {
5  type: 'collapsible',
6  label: 'Background Settings',
7  fields: [
8    COLOR({
9      name: 'bgColor',
10      label: 'Background Color',
11      required: false,
12    }),
13  ],
14}
15

How to Add a Custom Color Picker Field in Payload CMS