---
title: "Color Picker"
description: "A palette of swatches with a custom colour tile, for role and accent colours."
---

Use it where somebody gives a thing a colour: a role, a category, an embed's accent. A short palette covers the common choice in one click, and the larger tile opens the browser's own colour dialog for anything else. That tile wears the colour whenever the value is not one of the swatches.

The palette is data, not theme: these are values an application stores, so they are passed as a prop and are not `--newt-*` tokens.

_Live example of Color Picker — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add color-picker
```

Files written — React: components/ui/color-picker.tsx. Vue: components/ui/color-picker/ColorPicker.vue, components/ui/color-picker/index.ts.

## Usage

React:

```tsx
import { ColorPicker } from "@/components/ui/color-picker"
```

Vue:

```ts
import { ColorPicker } from "@/components/ui/color-picker"
```

## API reference

**`ColorPicker`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / v-model` | `string` | — | The chosen colour. In React, leave it undefined and pass `defaultValue` to let the component own it. |
| `onValueChange` | `(value: string) => void` | — | React only. Called with the new colour; Vue emits `update:modelValue`. |
| `swatches` | `{ value: string; label: string }[]` | `defaultSwatches` | The palette. `label` is what a screen reader calls the swatch. |
| `allowCustom` | `boolean` | `true` | Shows the tile that opens the browser's colour dialog. |
| `label` | `string` | `"Colour"` | Accessible name of the group. |
| `customLabel` | `string` | `"Custom colour"` | Accessible name of the custom tile. |
| `name` | `string` | — | Shared `name` of the swatch radios. One is generated when it is not given. |
| `disabled` | `boolean` | `false` | Dims the picker and stops it taking input. |

`defaultSwatches` is exported beside the component, so a palette can extend it instead of restating it.

## Accessibility

The swatches are a native radio set: `Tab` reaches the chosen one and the arrow keys move between them. A colour is never its own name, so every swatch needs a `label`. The chosen swatch is marked with a check as well as by its position, and the check carries a dark edge so it stays visible on a pale swatch. Show the chosen value somewhere as text or on the thing being coloured, as the example does.

`label`, `customLabel` and each swatch's `label` name the picker in your language. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Color Picker reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
