> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Color Field

> Store hex colors as text, pick them from swatches or a color picker, and show them as swatches everywhere.

`colorField` returns a [Text field](https://docs.frogbot.ai/fields/text.md) 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.

```ts theme={"theme":"tokyo-night"}
import { colorField } from 'frogbot'
import type { CollectionConfig } from 'frogbot'

export const Labels: CollectionConfig = {
  slug: 'labels',
  fields: [
    { name: 'name', type: 'text', required: true },
    colorField({ name: 'color', label: 'Color' }),
  ],
}
```

The result is a plain `text` field, so it works anywhere a field does, including inside groups, arrays, tabs and blocks.

## Config options

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | Required | Property name used in stored records and APIs. See [field names](https://docs.frogbot.ai/fields/overview.md#field-names). |
| `swatches` | `string[]` | Ten colors, see [Swatches](#swatches) | Colors the picker offers as one-click swatches, each as `#rgb` or `#rrggbb`. `[]` shows none. |
| `label` | `string \| Record<string, string> \| (({ i18n, t }) => string) \| false` | Generated from `name` | Label shown in the admin panel. Use an object keyed by language code for translations, or `false` to hide the label. |
| `required` | `boolean` | `false` | Rejects an empty value. |
| `unique` | `boolean` | `false` | Creates a unique database index for the field path. See [indexes](https://docs.frogbot.ai/database/indexes.md). |
| `index` | `boolean` | `false` | Creates a database index for faster queries. `unique` already creates one. |
| `localized` | `boolean` | `false` | Stores one value per configured locale. Ignored without [localization](https://docs.frogbot.ai/configuration/localization.md) or inside a localized parent. |
| `defaultValue` | `string` or `({ locale, req, user }) => value` | — | Value used when the field has no value. See [default values](https://docs.frogbot.ai/fields/overview.md#default-values). |
| `validate` | `Validate` | — | Runs after the built-in validation and the hex color check, and adds to them rather than replacing them. See [validation](https://docs.frogbot.ai/fields/overview.md#validation). |
| `hooks` | `{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }` | — | Arrays of `FieldHook` functions for each phase. See [field hooks](https://docs.frogbot.ai/hooks/fields.md). |
| `access` | `{ create, read, update }` | Allowed | `FieldAccess` functions for each operation. See [field access control](https://docs.frogbot.ai/access-control/fields.md). |
| `hidden` | `boolean` | `false` | Removes the field from API responses and the admin panel while keeping stored data. |
| `saveToJWT` | `boolean \| string` | `false` | In an auth-enabled collection, copies the value into the user's token. A string sets the token key. See [token data](https://docs.frogbot.ai/authentication/token-data.md). |
| `virtual` | `boolean \| string` | `false` | `true` skips database storage; a string reads a value through a relationship path. Virtual fields are read-only in the admin panel unless `admin.readOnly` is `false`. See [virtual fields](https://docs.frogbot.ai/fields/overview.md#virtual-field-configuration). |
| `disableDuplicate` | `boolean` | `false` | Leaves the value out when a document is duplicated, so the copy uses `defaultValue`. |
| `admin` | `object` | — | Admin-panel options. See [Admin options](#admin-options). |
| `custom` | `Record<string, any>` | — | Server-only metadata for your own code and plugins. Use `admin.custom` for data the browser also needs. |
| `jsonSchema` | `Array<({ jsonSchema }) => JSONSchema4>` | — | Functions that modify the JSON Schema used by [type generation](https://docs.frogbot.ai/typescript/generating-types.md) and agents. They run after the color field's own entry. See [Agents and generated types](#agents-and-generated-types). |

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:

```text theme={"theme":"tokyo-night"}
colorField "color": hasMany is not supported
```

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.

| Value | Result |
| - | - |
| `#3b82f6`, `#3B82F6`, `#fff`, `#F0a` | Accepted |
| `3b82f6` | Rejected: the `#` is required |
| `#3b82f6ff`, `#3b8f` | Rejected: alpha digits aren't accepted |
| `blue`, `rgb(59, 130, 246)`, `hsl(217 91% 60%)` | Rejected: only hex colors are accepted |
| ` #fff`, `#fff ` | Rejected: no spaces around the color |

A rejected value fails with:

```text theme={"theme":"tokyo-night"}
Enter a hex color such as #3b82f6.
```

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:

```ts theme={"theme":"tokyo-night"}
colorField({ name: 'color', swatches: ['#0f766e', '#b45309', '#be123c'] })
```

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:

```text theme={"theme":"tokyo-night"}
colorField "color": swatch "teal" is not a #rgb or #rrggbb color
```

## Admin options

Color fields support the standard [field admin options](https://docs.frogbot.ai/fields/overview.md#admin-options), plus these input options:

| Option | Type | Default | Description |
| - | - | - | - |
| `placeholder` | `string \| Record<string, string>` | `#3b82f6` | Placeholder text. Use an object keyed by language code for translations. |
| `autoComplete` | `string` | — | Value of the input's `autocomplete` attribute. |

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](https://docs.frogbot.ai/admin/overview.md), on [Board](https://docs.frogbot.ai/admin/collection-board.md) cards and in [Calendar](https://docs.frogbot.ai/admin/collection-calendar.md) 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`](https://docs.frogbot.ai/admin/collection-list#editing-cells-in-place), 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`](#reading-colors-in-your-code) 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](https://docs.frogbot.ai/plugins/mcp.md) and in [generated types](https://docs.frogbot.ai/typescript/generating-types.md):

```text theme={"theme":"tokyo-night"}
Hex color as #rrggbb or #rgb, for example #3b82f6
```

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.

```ts theme={"theme":"tokyo-night"}
colorField({ name: 'color', admin: { description: 'Label color' } })
```

```text theme={"theme":"tokyo-night"}
Label color (hex color as #rrggbb or #rgb, for example #3b82f6)
```

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:

```ts theme={"theme":"tokyo-night"}
colorField({
  name: 'color',
  jsonSchema: [({ jsonSchema }) => ({ ...jsonSchema, description: 'Six-digit hex color' })],
})
```

```text theme={"theme":"tokyo-night"}
Six-digit hex color
```

## 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:

```tsx theme={"theme":"tokyo-night"}
'use client'

import { getHexColor } from 'frogbot/fields'

export function LabelDot({ value }: { value: string | null }) {
  const color = getHexColor({ value })

  return color ? <span style={{ backgroundColor: color }} /> : null
}
```

| Argument | Type | Default | Description |
| - | - | - | - |
| `value` | `unknown` | Required | The stored color. |

`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](#accepted-colors).

## 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`](https://docs.frogbot.ai/fields/overview#cell), as shown for [Money fields](https://docs.frogbot.ai/fields/money.md#custom-components). As with any custom Cell, it appears only in the List view. Board cards and Calendar events keep the standard swatch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.