# ColorPicker

Solid colour picker: 2D area + hue/alpha sliders + a format-aware value row.
The format selector switches the value field between a single hex string and
per-channel inputs (rgb/hsl/hwb/oklch — hex default; parses/edits on commit)
with a copy button. Accepts a `var(--x)` value: it's shown as a variable badge
with an opportunistically resolved swatch (never required to resolve — admin
contexts) and editing any control overrides it with a concrete colour.

```tsx
import { ColorPicker, ColorArea, ColorSlider } from '@tangible/ui';
```

Interactive docs and examples: [ColorPicker in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-colorpicker--docs).

## ColorPicker props

| Prop | Type | Default | Description |
| - | - | - | - |
| `alpha?` | `boolean` | `true` | Show the alpha slider (and keep alpha in the emitted value). |
| `aria-label?` | `string` | | Accessible name for the picker group. Takes precedence over `labels.group`. Defines a string value that labels the current element. |
| `className?` | `string` | | |
| `defaultFormat?` | `"hex" \| "hsl" \| "hwb" \| "oklch" \| "rgb"` | `'hex'` | Uncontrolled initial format. |
| `defaultValue?` | `string` | `'#000000'` | Uncontrolled initial value. |
| `disabled?` | `boolean` | | |
| `format?` | `"hex" \| "hsl" \| "hwb" \| "oklch" \| "rgb"` | | Controlled format for the value field. |
| `formats?` | `ColorFormat[]` | `['hex','rgb','hsl','hwb','oklch']` | Formats offered in the format selector, in order. The selector is hidden when only one is supplied. |
| `labels?` | `ColorPickerLabels` | | Override any user-facing string for i18n. |
| `onFormatChange?` | `(format: ColorFormat) => void` | | |
| `onValueChange?` | `(value: string) => void` | | |
| `value?` | `string` | | Controlled value — a CSS colour OR a `var(--x[, fallback])` reference. |

Also accepts the standard attributes of `HTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## ColorArea props

2D saturation × value surface. The background is the current hue with a white→hue horizontal gradient (saturation) and a transparent→black vertical gradient (value); the thumb sits at (s, 1 − v). Pointer-draggable and keyboard-adjustable (arrows; Shift = coarse). role="slider" with a 2D aria-valuetext — a pragmatic model for a 2D picker; the a11y pass may refine to paired sliders.

| Prop | Type | Default | Description |
| - | - | - | - |
| `hsva` | `Hsva` | | |
| `onValueChange` | `(next: { s: number; v: number }) => void` | | Fires with the new saturation/value (0..1) as the thumb moves. |
| `aria-label?` | `string` | `'Saturation and brightness'` | |
| `className?` | `string` | | |
| `disabled?` | `boolean` | | |
| `valueText?` | `string` | | Overrides the default "Saturation X%, brightness Y%" announcement. |

## ColorSlider props

1D colour slider — the hue and alpha controls both use this. Pointer-draggable and keyboard-adjustable (arrows / Home / End; Shift = coarse).

| Prop | Type | Default | Description |
| - | - | - | - |
| `onValueChange` | `(value: number) => void` | | |
| `track` | `string` | | CSS background for the gradient track. |
| `value` | `number` | | |
| `aria-label?` | `string` | | |
| `checkerboard?` | `boolean` | | Show the alpha checkerboard behind the track. |
| `className?` | `string` | | |
| `disabled?` | `boolean` | | |
| `max?` | `number` | `100` | |
| `min?` | `number` | `0` | |
| `step?` | `number` | `1` | |
| `valueText?` | `string` | | |

## Other exports

- `defaultColorPickerLabels`: `Required<ColorPickerLabels>`

## Examples

- [Per-channel inputs (RGB)](https://storybook-tangible-ui.pages.dev/?path=/story/forms-colorpicker--channels): Non-hex formats show per-channel `spinbutton` inputs. Type a value or use ArrowUp/Down (Shift = ×10); values are clamped to range. The compact chevron opens a menu previewing the colour converted into every format.

- [Restricted formats](https://storybook-tangible-ui.pages.dev/?path=/story/forms-colorpicker--restricted-formats): Use `formats` to limit which formats the selector offers (in order). With a single format the selector is hidden entirely.

Other stories: Area + Sliders, Full picker, var() value, Disabled ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-colorpicker--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-color-area-radius`
- `--tui-color-area-min-height`
- `--tui-color-area-thumb-size`
- `--tui-color-slider-radius`
- `--tui-color-slider-height`
- `--tui-color-slider-thumb-size`
- `--tui-color-field-swatch-border`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/forms-colorpicker--docs