# Cell Color Picker

A compact color swatch picker for inline use in a Data Table cell.

- Category: Forms
- Page: https://wunderui.com/components/cell-color-picker
- Tier: Free

## Install

```bash
npx wunderui-cli add cell-color-picker
```

## Import

```tsx
import { CellColorPicker } from "@/components/wunderui/table-cells"
```

## Minimal usage

Then use it inside a table cell:

```tsx
import { useState } from "react"
import { CellColorPicker } from "@/components/ui/cell-color-picker"
import { TableCell } from "@/components/ui/table"

export function LabelColourCell() {
  const [color, setColor] = useState("#12AFF0")

  return (
    <TableCell>
      <CellColorPicker value={color} onValueChange={setColor} />
    </TableCell>
  )
}
```

Expected result: You see a 24 px blue circle in the cell. Click it to open a popover with six colours, choose one and the circle takes that colour.

## Usage

```tsx
import { useState } from "react"
import { CellColorPicker } from "@/components/ui/cell-color-picker"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const LABELS = [
  { name: "Billing", color: "#12AFF0" },
  { name: "Design", color: "#A584F3" },
  { name: "Support", color: "#F3654A" },
]

export function Example() {
  const [labels, setLabels] = useState(LABELS)
  const setColor = (name: string, color: string) =>
    setLabels((rows) => rows.map((row) => (row.name === name ? { ...row, color } : row)))
  
  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Ticket labels">
        <TableHeader>
          <TableRow>
            <TableHead>Label</TableHead>
            <TableHead className="w-40">Colour</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {labels.map((label) => (
            <TableRow key={label.name}>
              <TableCell role="rowheader" className="font-medium">{label.name}</TableCell>
              <TableCell>
                <CellColorPicker
                  value={label.color}
                  aria-label={`${label.name} colour`}
                  onValueChange={(color) => setColor(label.name, color)}
                />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

## When to use

### Use Cell Color Picker for

- A colour column in a table, such as a label colour, a calendar colour or a chart series
- A short fixed palette of six colours
- Colours that are stored as hex strings

### Use something else

- [Color Picker](https://wunderui.com/components/color-picker) for a free colour with hex, RGB or HSL entry and opacity
- [Badge](https://wunderui.com/components/badge) for a status or category in a fixed set of tints that the person does not choose
- [Cell Select](https://wunderui.com/components/cell-select) for a choice between named options instead of colours

## Keyboard

The swatch button and every colour in the popover are native buttons, so the browser handles focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control in the table, row by row. Each swatch button is one Tab stop. |
| `Enter` or `Space` | On the swatch button: opens the popover. Tab then moves into it, through the six colours. |
| `Enter` or `Space` | On a colour: chooses it and calls `onValueChange` with its hex value. The popover stays open, so you can try another colour. |
| `Escape` | Closes the popover and returns focus to the swatch button. |

The popover has no arrow-key navigation. Each of the six swatches is its own Tab stop.

## Behavior

What the cell colour picker does itself, and what it leaves to the table around it.

- **Controlled:** CellColorPicker keeps no state. You supply the value, a choice calls the change handler with the hex string, and nothing changes until you set the value.
- **The palette:** The palette has six fixed colours: blue, purple, orange-red, yellow, green and pink. A value outside the set shows on the swatch button, but no popover colour is marked.
- **Accessible name:** Without a label the button reads Colour, its hex value and Choose a colour. With a label like Billing colour it reads the label plus the hex, so mark the first row cell as a row header too.
- **Popover:** The popover opens below the swatch and is not clipped by the table card. It stays open after a choice and closes with Escape or a click outside.
- **Active colour:** The matching swatch is marked pressed and has a ring. A colour outside the palette marks none.
- **Figma states:** The Figma Editable Cell set has View, Edit, Changed, Saving, Error and Disabled. CellColorPicker has no props for these states.
- **Motion:** The popover fades and scales in, then leaves faster. A swatch grows by 10 % on hover.
- **Reduced motion:** With reduced motion the popover opens without moving and the swatches no longer grow. Only the fade stays.

## Anatomy

- `Table`: The table the cell sits in. The first column holds the row names, the header row names the columns, and the picker lives in a table cell.
- `Column header`: The header of the colour column. It says what the colour is for, such as Colour or Chart colour.
- `Row header`: The first cell of the row, marked as the row header, which says which label, calendar or series the colour belongs to. Give the swatch the same name as its aria-label.
- `CellColorPicker`: A round swatch button that opens a six-colour popover. Built for a table cell, it returns the chosen colour as a hex string, and you hold the value and write it back on change.
- `Swatch button`: The 24 px round trigger filled with the current colour. Its name is the label plus the hex value, and it announces a dialog.
- `Popover`: The popover with the six swatches in one row. Its name comes from the aria-label, Choose a colour by default, and it stays open after a choice.
- `Swatch`: One of the six colour buttons in the popover, named by its hex value. The active one has a ring and is marked pressed.

## Best practices

### Do

- Keep the value as a hex string and store it in the change handler. The trigger names itself with that value.
- Pass an aria-label that names the row, such as Billing colour, so the swatch reads Billing colour plus its hex value. Mark the first cell of each row as a row header too.
- Show the effect of the choice nearby, such as a legend bar or a preview, so nobody judges the colour from a 24 px circle alone.
- Give the colour column a header that says what the colour is for, and centre the swatch in a narrow column.

### Don't

- Don't expect colours outside the six swatches. Another value still shows on the trigger, but no swatch is marked and people can only pick from the six.
- Don't use it outside a table row, since it is 24 px wide and has no visible label. Use ColorPicker for a labelled field with hex entry and opacity.
- Don't use colour as the only carrier of meaning. Pair it with the name of the label or series, as the row header does.
- Don't expect the Figma Editable Cell states (Edit, Changed, Saving, Error, Disabled). It only has a value and a change handler.

## API reference

### CellColorPicker

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: string) => void |  | Called with the hex string of the swatch the person chose. The popover stays open afterwards. |
| value* | string |  | The current colour as a hex string, such as `#12AFF0`. It is a controlled value. A value outside the six swatches shows on the button but marks no swatch. |
| aria-label | string |  | The accessible name of the swatch button, such as `Billing colour`. The button is then named `<aria-label>, <hex>`; the popover uses the label as its name. Without it the button is named `Colour <hex>. Choose a colour`. |

## Examples

### Colour: the six swatches

```tsx
import { useState } from "react"
import { CellColorPicker } from "@/components/ui/cell-color-picker"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export function Example() {
  const [color, setColor] = useState("#12AFF0")

  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Ticket labels">
        <TableHeader>
          <TableRow>
            <TableHead>Label</TableHead>
            <TableHead className="w-40">Colour</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          <TableRow>
            <TableCell role="rowheader" className="font-medium">Billing</TableCell>
            <TableCell>
              <CellColorPicker value={color} aria-label="Billing colour" onValueChange={setColor} />
            </TableCell>
          </TableRow>
        </TableBody>
      </Table>
    </div>
  )
}
```

## In context

### Ticket labels: a colour for each label

A Colour column beside the name and the count. Each swatch is named after its value and sits in its label's row.

```tsx
import { useState } from "react"
import { CellColorPicker } from "@/components/ui/cell-color-picker"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const LABELS = [
  { name: "Billing", tickets: 42, color: "#12AFF0" },
  { name: "Bug report", tickets: 128, color: "#F3654A" },
  { name: "Feature request", tickets: 77, color: "#A584F3" },
  { name: "Account access", tickets: 35, color: "#1AD598" },
]

export function Example() {
  const [labels, setLabels] = useState(LABELS)
  const setColor = (name: string, color: string) =>
    setLabels((rows) => rows.map((row) => (row.name === name ? { ...row, color } : row)))

  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Ticket labels">
        <TableHeader>
          <TableRow>
            <TableHead>Label</TableHead>
            <TableHead className="w-24 text-right">Tickets</TableHead>
            <TableHead className="w-24 text-center">Colour</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {labels.map((label) => (
            <TableRow key={label.name}>
              <TableCell role="rowheader" className="font-medium">{label.name}</TableCell>
              <TableCell className="text-right tabular-nums">{label.tickets}</TableCell>
              <TableCell className="text-center">
                <CellColorPicker value={label.color} aria-label={`${label.name} colour`} onValueChange={(color) => setColor(label.name, color)} />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

### Chart series: the bar follows the colour

The bar under the table uses the chosen colours, so each choice shows at once. The popover stays open after a choice, so you can compare two colours.

```tsx
import { useState } from "react"
import { CellColorPicker } from "@/components/ui/cell-color-picker"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const SERIES = [
  { name: "Revenue", share: 58, color: "#12AFF0" },
  { name: "Refunds", share: 27, color: "#F3654A" },
  { name: "Credits", share: 15, color: "#FACA4A" },
]

export function Example() {
  const [series, setSeries] = useState(SERIES)
  const setColor = (name: string, color: string) =>
    setSeries((rows) => rows.map((row) => (row.name === name ? { ...row, color } : row)))

  return (
    <div className="w-full overflow-hidden rounded-xl border border-border bg-card">
      <Table aria-label="Chart series">
        <TableHeader>
          <TableRow>
            <TableHead>Series</TableHead>
            <TableHead className="w-24 text-right">Share</TableHead>
            <TableHead className="w-24 text-center">Colour</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {series.map((item) => (
            <TableRow key={item.name}>
              <TableCell role="rowheader" className="font-medium">{item.name}</TableCell>
              <TableCell className="text-right tabular-nums">{item.share}%</TableCell>
              <TableCell className="text-center">
                <CellColorPicker value={item.color} aria-label={`${item.name} colour`} onValueChange={(color) => setColor(item.name, color)} />
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <div className="flex gap-1 border-t border-border p-4" aria-hidden>
        {series.map((item) => (
          <span key={item.name} className="h-2 rounded-full" style={{ flexGrow: item.share, backgroundColor: item.color }} />
        ))}
      </div>
    </div>
  )
}
```

## For AI agents

`get_component("cell-color-picker")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
