# Color field

> Native colour picker as the swatch, a hex input kept in sync, and preset swatches from the kit's categorical palette. Value is always #rrggbb.

- Group: Forms
- Status: stable
- Aliases: color-picker, colour-field
- HTML page: https://design.ipmnx.com/components/color-field/
- Spec: https://design.ipmnx.com/design/#nx-color-field

## Preview

**Brand colour** Presets default to the chart palette, so a chosen colour matches the charts.

```html
<div class="nx-field">
  <label class="nx-field__label" for="brand-color">Colour</label>
  <div class="nx-color">
    <input type="color" class="nx-color__picker" aria-label="Colour"
        value="#2a78d6">
    <input id="brand-color" class="nx-field__input nx-color__hex"
        value="#2a78d6" maxlength="7">
    <div class="nx-color__presets" role="group" aria-label="Colour">
      <button type="button" class="nx-color__preset"
          style="background:#2a78d6" aria-label="Blue #2a78d6"
          aria-pressed="true"></button>
      <button type="button" class="nx-color__preset"
          style="background:#1baf7a" aria-label="Aqua #1baf7a"
          aria-pressed="false"></button>
      <button type="button" class="nx-color__preset"
          style="background:#eda100" aria-label="Yellow #eda100"
          aria-pressed="false"></button>
    </div>
  </div>
</div>
```

```tsx
const [color, setColor] = useState("#2a78d6");
<NxColorField
  label="Colour"
  value={color}
  onChange={setColor}
  name="color"
  clearable
/>
```

## API

### React props (NxKit)

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` |   | yes | Visible label; also names the picker unless pickerLabel is given. |
| `value` | `string` |   | yes | #rrggbb or "" (cleared). |
| `onChange` | `(value: string) => void` |   | yes | Called with a complete #rrggbb (lower case), or "" when cleared. Never with a half-typed value. |
| `presets` | `{ value: string; name: string }[]` | `NX_COLOR_PRESETS` |   | Swatches under the field; [] hides them. |
| `clearable` | `boolean` | `false` |   | Shows a clear button and lets an empty value through. |
| `name` | `string` | `undefined` |   | Form field name, on the hex input. |

### Classes

| Class | Description |
| --- | --- |
| `.nx-color` | Row: picker, hex input, presets |
| `.nx-color__picker` | Native input[type=color] styled as a field-height swatch |
| `.nx-color__hex` | Field input, monospace, 9.5ch |
| `.nx-color__preset` | 24px round swatch button; aria-pressed ring when selected |

## States

### invalid hex

```html
<div class="nx-field"><label class="nx-field__label" for="c2">Colour</label><div class="nx-color"><input type="color" class="nx-color__picker" aria-label="Colour" value="#000000"><input id="c2" class="nx-field__input nx-color__hex" value="#12" aria-invalid="true"></div></div>
```

## Accessibility

- The picker has its own accessible name (pickerLabel ?? label); the visible label points at the hex input.
- Preset buttons are named by colour name + hex and carry aria-pressed, never colour alone.

## Do / Don't

- Do: Store the hex the field gives you (#rrggbb) and validate it again on the server before it lands in a style attribute.
- Don't use a free-text input for colours. A typo silently produces no colour.

## Related

- [Field](https://design.ipmnx.com/components/field.md)
- [Select](https://design.ipmnx.com/components/select.md)

---

Source: registry.js (NX Design System)
