Skip to main content
colorField returns a Text field that stores a hex color such as #3b82f6. Every save checks that the value is a hex color, the admin panel edits it with swatches and a color picker and shows it as a swatch, and agents and generated types are told what the text means. You don’t name any components or write a validator.
The result is a plain text field, so it works anywhere a field does, including inside groups, arrays, tabs and blocks.

Config options

A color field holds one color of a fixed length, so hasMany, minRows, maxRows, minLength, maxLength and admin.rtl are not accepted. TypeScript rejects them, and setting any of them from JavaScript fails at startup with an error naming the field:
The hex value always reads left to right, even in a right-to-left locale.

Accepted colors

Every save checks the value, whether it comes from the admin panel, the REST API, GraphQL, the Local API or an agent. A color is # followed by three or six hex digits, in any letter case. A rejected value fails with:
An empty value skips the check; set required to reject it.

Swatches

The picker offers these swatches unless you set swatches: #6b7280 gray, #ef4444 red, #f97316 orange, #eab308 yellow, #22c55e green, #14b8a6 teal, #3b82f6 blue, #6366f1 indigo, #a855f7 purple and #ec4899 pink. Pass your own palette to match your app, or [] to show only the text input and the color picker:
A color listed twice, such as #fff and #FFFFFF, is offered once. Swatches are offered, not enforced: any hex color can still be typed or picked. Each swatch must be a hex color, or the app fails at startup with an error naming the field and the swatch:

Admin options

Color fields support the standard field admin options, plus these input options: FrogBot marks the field as a color in admin.custom.frogbot.kind, with its swatches. Your own admin.custom keys, and other keys under admin.custom.frogbot, are kept.

Display and editing

A color shows as a small swatch of the color followed by the value as stored, so #3B82F6 stays in capitals. The swatch has a thin outline, so white shows on a light background and black on a dark one. This works in the List, on Board cards and in Calendar events. An empty value shows nothing: no placeholder and no dash. A stored value that isn’t an accepted color, for example one saved before the field became a color field, shows as plain text with no swatch. In the document view, a color field has a text input for the hex value, a button showing the current color that opens the browser’s color picker, and the swatches below. Clicking a swatch or picking a color fills in the input; typing in the input updates the button. A read-only field shows the swatch and the value with no controls. In a list with editable, a color cell edits in place with the text input and the color picker button. The swatches are left out of the cell so it stays one row high. Enter saves and Esc cancels.

Stored value

Colors are stored exactly as typed or picked: the picker and the swatches write lowercase six-digit hex such as #3b82f6, and a typed #FFF stays #FFF. The REST API, GraphQL and the Local API return the stored text, and the generated TypeScript type is the same as a Text field’s, such as color?: string | null. getHexColor turns either form into lowercase six-digit hex, which helps when comparing colors.

Agents and generated types

A color field describes itself to agents using FrogBot’s MCP tools and in generated types:
With a string admin.description, or a translated one with an en entry, the color text is added after it in parentheses. The admin panel still shows only your description.
A function admin.description isn’t copied, so the color text stands alone. The text is English only. Generated types show the text as a comment above the property, and virtual fields don’t appear in MCP tool inputs. To change the text, add your own jsonSchema entry. It runs after the color field’s entry, so it can adjust or replace the description:

Reading colors in your code

getHexColor is the rule color fields use for the save check and the swatches. Import it from frogbot/fields, which is safe to use in browser code:
getHexColor returns the color as lowercase six-digit hex, so #F0A becomes #ff00aa. It returns undefined for an empty value and for any value that isn’t an accepted color.

Custom components

The color cell is ColorCell and the input is ColorField, both from @frogbotai/ui/admin. Your own admin.components.Cell or admin.components.Field replaces them, and other components such as Label, Description, Error, beforeInput and afterInput work as they do on a Text field. A custom Cell can draw the standard swatch inside its own markup with FieldCell, as shown for Money fields. As with any custom Cell, it appears only in the List view. Board cards and Calendar events keep the standard swatch.