Building your own custom fields in Payload is as easy as writing a React component. Any field type can be extended further to make your own custom field, right down to how it works in the admin panel. In this way, you can avoid reinventing everything about a field and only work on adding your custom business logic exactly how you need.

To demonstrate this, we're going to create a simple color picker component for use right in the Payload CMS admin panel. By the end of this guide, we'll have created a modular, reusable custom field that can be dropped into any Payload CMS app with ease.

The component will:

Store its value in the database as a string—just like the built-in text field type
Use a custom validator function for the color format, to enforce consistency on the frontend and backend
Handle sending and receiving data to the Payload API by leveraging Payload's useFieldType hook
Store and retrieve user-specific preferences using Payload's Preferences feature
Render a custom Cell component, showing the selected color in the List view of the admin panel

All the code written for this guide can be seen in the Custom Field Guide repository.

Get Started

You can use your own Payload app or start a new one for this guide. If you haven't started a project yet, you can get started easily by running npx create-payload-app in your terminal.

For more details on how to start an application, including how to do so from scratch, read the installation documentation.

Write the base field config

The first step is to create a new file in your app for our new field's config. That will let us import it to different collections wherever it is needed. Because we want our field to store a string in the database, just like the built-in text field type does, we'll set our field's type equal to text. That will tell Payload how to handle storing the data. We'll also write a simple validation function to tell the backend and frontend what to allow to be saved.

1import { Field } from 'payload/types';
2
3export const validateHexColor = (value: string): boolean | string => {
4  return value.match(/^#(?:[0-9a-fA-F]{3}){1,2}$/).length === 1 || `${value} is not a valid hex color`;
5}
6
7const colorField: Field = {
8  name: 'color',
9  type: 'text',
10  validate: validateHexColor,
11  required: true,
12};
13
14export default colorField;

Import the field in a collection

We'll import the field to an existing collection, so we can see it in use, before building it up a bit more.

/src/collections/ToDoLists.ts:

1import { CollectionConfig } from 'payload/types';
2import colorField from '../color-picker/config';
3
4const Todo: CollectionConfig = {
5  fields: [
6    colorField,
7  ]
8}

This is a good time to mention that because we're just dealing with JavaScript, you could import this field and use it anywhere. You could also change individual properties specific to this collection by destructuring the object and add extra properties you wish to set. To do that, in place of the imported colorField instead do { ...colorField, required: false }, or any other properties as needed.

Build the Edit Component

So far, the default Text component is still rendering in the admin panel. Let's swap that out with a custom component, and modify the field's config to include it.

Custom field components are just basic React components, so let's scaffold that out and then build the extra features one-by-one. Create a new file for the Field component:

/src/color-picker/InputField.tsx:

1import React from 'react'
2
3// this is how we'll interface with Payload itself
4import { useFieldType } from 'payload/components/forms';
5
6// we'll re-use the built in Label component directly from Payload
7import { Label } from 'payload/components/forms';
8
9// we can use existing Payload types easily
10import { Props } from 'payload/components/fields/Text';
11
12// we'll import and reuse our existing validator function on the frontend, too
13import { validateHexColor } from './config';
14
15// Import the SCSS stylesheet
16import './styles.scss';
17
18// keep a list of default colors to choose from
19const defaultColors = [
20  '#0F0F0F',
21  '#9A9A9A',
22  '#F3F3F3',
23  '#FF6F76',
24  '#FDFFA4',
25  '#B2FFD6',
26  '#F3DDF3',
27];
28
29const baseClass = 'custom-color-picker';
30
31const InputField: React.FC<Props> = (props) => {
32  const {
33    path,
34    label,
35    required
36  } = props;
37
38  const {
39    value = '',
40    setValue,
41  } = useFieldType({
42    path,
43    validate: validateHexColor,
44  });
45
46  return (
47    <div className={baseClass}>
48      <Label
49        htmlFor={path}
50        label={label}
51        required={required}
52      />
53      <ul className={`${baseClass}__colors`}>
54        {defaultColors.map((color, i) => (
55          <li key={i}>
56            <button
57              type="button"
58              key={color}
59              className={`chip ${color === value ? 'chip--selected' : ''} chip--clickable`}
60              style={{ backgroundColor: color }}
61              aria-label={color}
62              onClick={() => setValue(color)}
63            />
64          </li>
65          )
66        )}
67      </ul>
68    </div>
69  )
70};
71
72export default InputField;

You'll see above that Payload automatically provides our React component with the props that it needs. The most important prop is the path, which we pass on to the useFieldType hook. This hook allows us to set the field's value and have it work with the rest of the Payload form.

The component returns the markup for the component, complete with a Label and a list of clickable colors.

This won't be very functional until we add styling. Let's add a new line to import a new stylesheet: import './styles.scss';. Create that file and paste in the following SCSS:

/src/color-picker/styles.scss:

1@import '~payload/scss';
2
custom-color-picker {
&__colors {
  display: flex;
  flex-wrap: wrap;
  list-style: none;
  padding: 0;
  margin: 0;
}
11}
12
chip {
border-radius: 50%;
border: $style-stroke-width-m solid #fff;
height: base(1.25);
width: base(1.25);
margin-right: base(.5);
box-shadow: none;
20
&--selected {
  box-shadow: 0 0 0 $style-stroke-width-m $color-dark-gray;
}
24
&--clickable {
  cursor: pointer;
}
28}

The simple styles above will give the color "chips" a clickable circle to set the value and show which is currently selected.

Build the Cell

Another part of the custom component that we can add is a nice way to display the color right in a collection List. There, we can create the following:

/src/color-picker/Cell.tsx:

1
2import React from 'react';
3import { Props } from 'payload/components/views/Cell';
4import './styles.scss';
5
6const Cell: React.FC<Props> = (props) => {
7  const { cellData } = props;
8
9  if (!cellData) return null;
10
11  return (
12    <div
13      className="chip"
14      style={{ backgroundColor: cellData as string }}
15    />
16  )
17}
18
19export default Cell;

Note that we can reuse our styles here as we want the color "chip" to appear the same. We get the cellData from the Prop and that will be our saved hex values for the field.

Add the components to the Field

Now that we have a functional component to serve as our input, we can update color-picker/config.ts with a new admin property:

1import { Field } from 'payload/types';
2import InputField from './InputField';
3import Cell from './Cell';
4
5const colorField: Field = {
6  // ...
7  admin: {
8    components: {
9      Field: InputField,
10      Cell,
11    },
12  },
13};

Now is a good time to see it working! After you login and navigate to the url to create a new Todo item you will see the component and can use it to create a new Todo list

Back in the List view, you should also be able to see the color that was chosen right in the table. If you don't see the color column, expand the column list to include it.

Allowing users to add their own colors

What we have is nice if we want to control available color options closely, but we know our users want to add their own too. Let's add to the UI a way to do that and while we're at it we should store the user's newly added colors in Payload's user preferences to re-use color options without re-entering them every time.

To make the interactions possible, we'll add more state variables and useEffect hooks. We also need to import and use the validation logic from the config, and set the value in a new Input which we can import styles directly from Payload to make it look right.

User Preferences

By adding Payload's usePreferences() hook, we can get and set user specific data relevant to the color picker all persisted in the database without needing to write new endpoints. You will see we call setPreference() and getPreference() to get and set the array of color options specific to the authenticated user.

Note that the preferenceKey should be something completely unique across your app to avoid overwriting other preference data.

Now, for the complete component code:

/src/color-picker/InputField.tsx:

1import React, { useEffect, useState, useCallback, Fragment } from 'react'
2
3// this is how we'll interface with Payload itself
4import { useFieldType } from 'payload/components/forms';
5
6// retrieve and store the last used colors of your users
7import { usePreferences } from 'payload/components/preferences';
8
9// re-use Payload's built-in button component
10import { Button } from 'payload/components';
11
12// we'll re-use the built in Label component directly from Payload
13import { Label } from 'payload/components/forms';
14
15// we can use existing Payload types easily
16import { Props } from 'payload/components/fields/Text';
17
18// we'll import and reuse our existing validator function on the frontend, too
19import { validateHexColor } from './config';
20
21// Import the SCSS stylesheet
22import './styles.scss';
23
24// keep a list of default colors to choose from
25const defaultColors = [
'#0F0F0F',
'#9A9A9A',
'#F3F3F3',
'#FF6F76',
'#FDFFA4',
'#B2FFD6',
'#F3DDF3',
33];
34const baseClass = 'custom-color-picker';
35
36const preferenceKey = 'color-picker-colors';
37
38const InputField: React.FC<Props> = (props) => {
const {
  path,
  label,
  required
} = props;
44
const {
  value = '',
  setValue,
} = useFieldType({
  path,
  validate: validateHexColor,
});
52
const { getPreference, setPreference } = usePreferences();
const [colorOptions, setColorOptions] = useState(defaultColors);
const [isAdding, setIsAdding] = useState(false);
const [colorToAdd, setColorToAdd] = useState('');
57
useEffect(() => {
  const mergeColorsFromPreferences = async () => {
    const colorPreferences = await getPreference<string[]>(preferenceKey);
    if (colorPreferences) {
      setColorOptions(colorPreferences);
    }
  };
  mergeColorsFromPreferences();
}, [getPreference, setColorOptions]);
67
const handleAddColor = useCallback(() => {
  setIsAdding(false);
  setValue(colorToAdd);
71
  // prevent adding duplicates
  if (colorOptions.indexOf(colorToAdd) > -1) return;
74
  let newOptions = colorOptions;
  newOptions.unshift(colorToAdd);
77
  // update state with new colors
  setColorOptions(newOptions);
  // store the user color preferences for future use
  setPreference(preferenceKey, newOptions);
}, [colorOptions, setPreference, colorToAdd, setIsAdding, setValue]);
83
return (
  <div className={baseClass}>
    <Label
      htmlFor={path}
      label={label}
      required={required}
    />
    {isAdding && (
      <div>
        <input
          className={`${baseClass}__input`}
          type="text"
          placeholder="#000000"
          onChange={(e) => setColorToAdd(e.target.value)}
          value={colorToAdd}
        />
        <Button
          className={`${baseClass}__btn`}
          buttonStyle="primary"
          iconPosition="left"
          iconStyle="with-border"
          size="small"
          onClick={handleAddColor}
          disabled={validateHexColor(colorToAdd) !== true}
        >
          Add
        </Button>
        <Button
          className={`${baseClass}__btn`}
          buttonStyle="secondary"
          iconPosition="left"
          iconStyle="with-border"
          size="small"
          onClick={() => setIsAdding(false)}
        >
          Cancel
        </Button>
      </div>
    )}
    {!isAdding && (
      <Fragment>
        <ul className={`${baseClass}__colors`}>
          {colorOptions.map((color, i) => (
            <li key={i}>
              <button
                type="button"
                key={color}
                className={`chip ${color === value ? 'chip--selected' : ''} chip--clickable`}
                style={{ backgroundColor: color }}
                aria-label={color}
                onClick={() => setValue(color)}
              />
            </li>
          )
          )}
        </ul>
        <Button
          className="add-color"
          icon="plus"
          buttonStyle="icon-label"
          iconPosition="left"
          iconStyle="with-border"
          onClick={() => {
            setIsAdding(true);
            setValue('');
          }}
        />
      </Fragment>
    )}
  </div>
)
155};
156export default InputField;

We made a lot of changes—hopefully the code speaks for itself. Everything we did adds to the interactivity and usability of the field.

Styling the input to look like Payload UI

Lastly we want to finish off the styles of our input with a few new pieces.

Update your styles.scss with the following:

/src/color-picker/styles.scss:

1@import '~payload/scss';
2
add-color.btn {
margin: 0;
padding: 0;
border: $style-stroke-width-m solid #fff;
7}
8
custom-color-picker {
&__btn.btn {
  margin: base(.25);
12
  &:first-of-type {
    margin-left: unset;
  }
}
17
&__input {
  // Payload exports a mixin from the vars file for quickly applying formInput rules to the class for our input
  @include formInput
}
22
&__colors {
  display: flex;
  flex-wrap: wrap;
  list-style: none;
  padding: 0;
  margin: 0;
}
30}
31
chip {
border-radius: 50%;
border: $style-stroke-width-m solid #fff;
height: base(1.25);
width: base(1.25);
margin-right: base(.5);
box-shadow: none;
39
&--selected {
  box-shadow: 0 0 0 $style-stroke-width-m $color-dark-gray;
}
43
&--clickable {
  cursor: pointer;
}
47}
48

Closing Remarks

The custom color picker in this guide serves as an example of one way you could extend the UI to create a better authoring experience for users.

I hope you're inspired to create your own fantastic UI components using Payload CMS. Feel free to share what you build in the GitHub discussions.