---
title: Colorpicker
description: An inline color swatch picker with an optional hex input.
---
import Source from './_generated/colorpicker.mdx';

An inline swatch grid for choosing a color from presets — a radiogroup of color circles with platform-correct selection chrome, plus an optional free-form hex input. Values are canonical lowercase `#rrggbb` hex strings.

<DemoFrame component="colorpicker" />

## Installation

```bash
npx touchcn add colorpicker
```

## Usage

<CodeGroup>

```html Angular
<tcn-colorpicker [(value)]="color">
  <tcn-colorpicker-swatch value="#007aff" label="Blue" />
  <tcn-colorpicker-swatch value="#34c759" label="Green" />
</tcn-colorpicker>
```

```tsx React
import { TcnColorpicker, TcnColorpickerSwatch } from '@/components/ui/colorpicker';

<TcnColorpicker value={color} onValueChange={setColor}>
  <TcnColorpickerSwatch value="#007aff" label="Blue" />
  <TcnColorpickerSwatch value="#34c759" label="Green" />
</TcnColorpicker>
```

```vue Vue
<script setup lang="ts">
import { TcnColorpicker, TcnColorpickerSwatch } from '@/components/ui/colorpicker';
</script>

<template>
  <TcnColorpicker v-model="color">
    <TcnColorpickerSwatch value="#007aff" label="Blue" />
    <TcnColorpickerSwatch value="#34c759" label="Green" />
  </TcnColorpicker>
</template>
```

</CodeGroup>

## Hex input

`TcnColorpickerInput` adds free-form hex entry — bind it to the same value as the grid. The draft commits (canonicalized) only on Enter or blur and only when valid; a color outside the presets simply leaves every swatch unchecked.

<CodeGroup>

```html Angular
<tcn-colorpicker-input [(value)]="color" label="Hex" />
```

```tsx React
<TcnColorpickerInput value={color} onValueChange={setColor} label="Hex" />
```

```vue Vue
<TcnColorpickerInput v-model="color" label="Hex" />
```

</CodeGroup>

## Props

### Colorpicker

| Prop            | Type                      | Default | Description                                                     |
| --------------- | ------------------------- | ------- | --------------------------------------------------------------- |
| `value`         | `string \| null`          | `null`  | Selected color (two-way bound); emitted as canonical `#rrggbb`. |
| `onValueChange` | `(value: string) => void` | —       | Change callback (React).                                        |
| `disabled`      | `boolean`                 | `false` | Disable the whole group.                                        |

### ColorpickerSwatch

| Prop       | Type      | Default | Description                                 |
| ---------- | --------- | ------- | ------------------------------------------- |
| `value`    | `string`  | —       | Swatch color (any hex form; canonicalized). |
| `label`    | `string`  | hex     | Accessible name.                            |
| `disabled` | `boolean` | `false` | Disable this swatch.                        |

### ColorpickerInput

| Prop            | Type                      | Default | Description                      |
| --------------- | ------------------------- | ------- | -------------------------------- |
| `value`         | `string \| null`          | `null`  | Committed color (two-way bound). |
| `onValueChange` | `(value: string) => void` | —       | Change callback (React).         |
| `label`         | `string`                  | —       | Field label.                     |
| `disabled`      | `boolean`                 | `false` | Disable the field.               |

<Source />