# Chroma Panel

> React color picker with wheel, sliders, palettes, image sampling and an eyedropper. Zero dependencies, accessible, TypeScript types included.

# Quick start

Source: /react/overview/quick-start

## Installation

```bash
npm install chroma-panel
```

There is no CSS import and no provider to set up.

## Anatomy

`ColorInput` renders a swatch button that opens the panel in a popover.

```tsx
import { ColorInput } from "chroma-panel";

<ColorInput defaultValue="#3366cc" />;
```

<ComponentPreview name="color-input-demo" />

## Controlled

Pass `value` and handle `onChange` to keep the color in your own state. Pass
`defaultValue` instead and the panel keeps it for you.

```tsx
import { useState } from "react";
import { ColorInput, type ColorChangeResult } from "chroma-panel";

export function BrandPicker() {
  const [color, setColor] = useState<string>("#3366cc");

  const handleChange = (result: ColorChangeResult): void => {
    setColor(result.hex);
  };

  return <ColorInput value={color} onChange={handleChange} />;
}
```

`onChange` fires continuously while you drag. `onChangeComplete` fires once when
you let go — use that one for saving, undo entries and network calls.

## Inline panel

`ChromaPanel` is the same panel without the popover, for when you want it on the
page.

<ComponentPreview name="chroma-panel-demo" />

## Smaller bundle

Importing `chroma-panel` registers all five modes. If you only need one or two,
import the shell and add the modes yourself.

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/wheel";

<ChromaPanel modes={["wheel"]} />;
```

That is 14.1 kB instead of 22.2 kB. Every mode has its own entry point — see
[entry points](/react/utils/entry-points).

<ComponentPreview name="chroma-panel-wheel-demo" />

## Next steps

- [Theming](/react/handbook/theming) — change how the panel looks
- [Controlled and uncontrolled](/react/handbook/controlled) — which props you own
- [ColorInput](/react/components/color-input) — the full prop reference

---

# Accessibility

Source: /react/overview/accessibility

You do not need to add anything.

Every color axis is a real `<input type="range">`, hidden visually, so keyboard
handling and screen-reader support come from the browser rather than a
reimplementation of it.

## What you get

- Arrows step. Shift+arrow and Page Up/Down step by ten. Home and End jump.
- The mode switcher is a tablist with a roving tab stop.
- Values are announced as text: "Hue 210 degrees", not a bare number.
- The popover traps focus, closes on Escape, and returns focus to the trigger.
- Swatches are buttons with accessible names.
- `prefers-reduced-motion` and forced-colors mode are both handled.

## Helpers for your own UI

```ts
import { readableTextColor, contrastRatio } from "chroma-panel";

readableTextColor("#001f3f"); // '#ffffff'
contrastRatio("#fff", "#001f3f"); // WCAG 2.1 ratio
```

`readableTextColor` uses APCA rather than plain luminance. It picks white over
mid-blues, where the older method wrongly picks black.

More in [Contrast](/react/utils/contrast).

## Data attributes

<DataAttributesTable />

---

# Releases

Source: /react/overview/releases

<ReleaseTimeline />

## Canary releases

Pre-release versions are published under the `next` tag so they never reach
anyone who has not asked for them. Install one by name:

```bash
npm install chroma-panel@next
```

They carry a **Pre-release** badge on the timeline above, and are never marked
**Latest**. Treat them as a preview: the API in a canary can still change before
it lands in a stable release.

## Versioning

The package follows semantic versioning. A breaking change to any of the
following is a major release:

- The props documented under [Components](/react/components/color-input)
- The exports of any [entry point](/react/utils/entry-points)
- The `--cp-*` custom properties and `data-cp-*` attributes

Internal class names that are not listed in the API reference are not part of
the public surface and can change in a patch.

## Upgrading

```bash
npm install chroma-panel@latest
```

## Full release notes

The timeline above shows the highlights of each release. The complete notes,
including every commit and contributor, are on GitHub.

- [Releases](https://github.com/re-sohail/chroma-panel/releases)
- [Compare any two versions](https://github.com/re-sohail/chroma-panel/compare)

---

# About

Source: /react/overview/about

## Why the color survives a round trip

HSV has two places where information disappears. At zero saturation there is no
hue to speak of, and at zero brightness there is neither. Pickers that keep
their state as RGB or hex hit this constantly: drag brightness to black and back
up, and the hue you picked comes back as red.

This one keeps the full HSVA value and merges changes into it instead of
replacing it, so dragging to an extreme and back returns the color you started
with.

<Callout variant="note" title="Reading hex when you need precision">
  `hex` is rounded to 8 bits per channel. Store `hsva` and pass it back to
  `value` if a color has to survive a round trip unchanged.
</Callout>

## Size

Measured as the increase in a real Vite production build, gzipped, with React
external.

| What you import     | Added to your app |
| ------------------- | ----------------- |
| all five modes      | 22.2 kB           |
| shell plus one mode | 14.1 kB           |

`dependencies` is empty. `react` and `react-dom` are peer dependencies, so the
copy already in your app is the one that gets used.

## Compatibility

|                  |                                                         |
| ---------------- | ------------------------------------------------------- |
| React            | 16.14 and newer, including 19                           |
| React DOM        | Required. The popover renders through `createPortal`    |
| Browsers         | Chrome 123, Firefox 120, Safari 17.5                    |
| TypeScript       | Types included, no `@types` package needed              |
| Modules          | ESM and CommonJS                                        |
| Server rendering | Safe. Browser-dependent files are marked `'use client'` |

See [browser support](/react/handbook/browser-support) for what sets the floor.

## Licence

MIT, by [Sohail Khan](https://resohail.me).

---

# Theming

Source: /react/handbook/theming

```css
.cp-root {
  --cp-accent: #e5484d;
  --cp-radius-lg: 4px;
  --cp-width: 280px;
}
```

Anything you do not set keeps its default. The panel follows the system color
scheme unless you pass `theme`.

## The full set

```css
.cp-root {
  --cp-surface: #ffffff;
  --cp-surface-raised: #f4f4f6;
  --cp-border: #d6d6da;
  --cp-text: #1c1c1e;
  --cp-text-muted: #6b6b70;
  --cp-accent: #2d7ff9;
  --cp-focus: #2d7ff9;
  --cp-radius-lg: 16px;
  --cp-radius: 10px;
  --cp-width: 320px;
  --cp-disc-size: 196px;
  --cp-panel-h: 344px;
  --cp-control-height: 32px;
}
```

Two are worth knowing about before you change them.

`--cp-control-height` sizes the tab bar, the text inputs, the eyedropper and the
footer swatch together, so one value scales every control at once.

`--cp-panel-h` is the height set aside for the mode content. It is the same in
every mode, which is what stops the panel resizing when you switch tabs. Content
taller than it scrolls. Set it to `auto` if you would rather each mode sized
itself, and accept that the panel will jump.

## Fitting a container

The panel is a fixed 320px wide and reserves a fixed height for its mode
content. Both are variables, so it can be made to follow whatever box you put it
in — this is what the cards on the home page do.

```tsx
<ChromaPanel
  style={{
    "--cp-width": "100%",
    "--cp-panel-h": "auto",
  }}
/>
```

`--cp-width: 100%` lets the panel fill its parent. Nothing else has to change:
the wheel is sized `min(100%, var(--cp-disc-size))`, so it scales down with the
panel rather than overflowing.

`--cp-panel-h` is the height set aside for the mode content, and it is the one
worth understanding:

| Value                 | What happens                                                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| a length, the default | Every mode is that tall, so switching tabs never resizes the panel. A mode with less content than that shows empty space below it. |
| `auto`                | Each mode is as tall as its own content — no empty space, but the panel resizes when you switch tabs.                              |

Showing a single mode, `auto` is almost always what you want: there is nothing
to switch to, so the reserved height only leaves a gap.

<Callout variant="note" title="Capping a tall mode">
  A length only caps the content when the panel has a height to divide up. With
  an auto-height panel the content grows past it instead. Give the panel a
  `height` as well and the mode content scrolls within it — `.cp-panel-host` is
  already `overflow-y: auto`.
</Callout>

```tsx
// Fills its container, and scrolls the palette rather than growing the page.
<ChromaPanel
  modes={["palettes"]}
  style={{ "--cp-width": "100%", height: 420 }}
/>
```

## If the panel looks wrong

The stylesheet lives in `@layer chroma-panel`, so your CSS always wins. That also
means CSS you did not aim at the picker wins. Any unlayered element rule in your
app beats every rule here, however specific:

```css
/* This restyles the picker's swatches and tabs too. */
button {
  border-radius: 7px;
}
```

If the geometry looks off, look for a rule like that first. Scope it, or put your
resets in a layer:

```css
@layer reset, chroma-panel, utilities;
```

## Loading the CSS yourself

For a strict `style-src` policy, or to extract critical CSS:

```tsx
import "chroma-panel/styles.css";

<ColorInput injectStyles={false} />;
```

Injection is keyed on `getRootNode()`. The picker works inside a shadow root or
an iframe, and many panels still produce one `<style>` element.

<Callout variant="warning" title="This does not shrink your bundle">
  `injectStyles={false}` only stops the panel writing a `<style>` tag. The CSS is
  imported by the module either way. Use it for CSP or critical CSS.
</Callout>

## API reference

### Styling functions

<SignatureList names="injectStyles, setStyleNonce" />

### CSS variables

<CssVariablesTable />

---

# Styling with Tailwind

Source: /react/handbook/tailwind

```tsx
<ColorInput
  classNames={{
    root: "shadow-2xl ring-1 ring-white/10",
    trigger: "h-8 w-12 rounded-lg",
  }}
/>
```

## Cascade layers

The package ships its rules inside `@layer chroma-panel`. Tailwind v4 emits
`@layer theme, base, components, utilities`, and a layer declared later sorts
after — so an undeclared `chroma-panel` layer would beat your utility classes.

Declare the order explicitly so utilities still win:

```css
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "chroma-panel/style.css";
@import "tailwindcss/utilities.css" layer(utilities);
```

That puts the panel after preflight, so it is not flattened by the reset, and
before utilities, so `classNames` still overrides it. This site is built exactly
this way.

<Callout variant="note" title="Importing from a component instead">
  `import "chroma-panel/style.css"` inside a component lands after your
  utilities in the bundle, which inverts the order above. Import it from your
  stylesheet.
</Callout>

---

# Composition

Source: /react/handbook/composition

There are two ways to build on this package, and which one you want depends on
whether your UI lives inside the panel.

## Inside the panel: a custom mode

A mode is plain data, so adding one changes no existing file:

```tsx
import { registerMode, ChromaPanel } from "chroma-panel";

registerMode({
  id: "brand",
  label: "Brand colors",
  icon: BrandIcon,
  Panel: BrandPanel, // reads the colour with usePanel()
});

<ChromaPanel modes={["wheel", "brand"]} />;
```

Inside `BrandPanel` you can use the panel's own controls —
[ColorArea](/react/components/color-area),
[ChannelSlider](/react/components/channel-slider),
[Swatch](/react/components/swatch) and the rest. They read the colour through
`usePanel()`, so they only work inside a `ChromaPanel`.

More in [custom modes](/react/modes/custom).

## Outside the panel: the store and hooks

For a picker that is not inside a `ChromaPanel`, make a store and read it with
the hooks.

```tsx
import { createColorStore } from "chroma-panel/core";
import { useColorValue } from "chroma-panel";

const store = createColorStore({ h: 220, s: 75, v: 80, a: 1 });

function Preview() {
  const color = useColorValue(store);

  return <div style={{ background: `hsl(${color.h} 50% 50%)` }} />;
}
```

<Callout variant="warning" title="The primitives are not standalone">
  `ColorArea`, `ChannelSlider` and the others read `usePanel()`. Rendering one
  outside a `ChromaPanel` will not work. Use `createColorStore` and the hooks
  instead.
</Callout>

## Sharing one colour between panels

Pass the same store to more than one component and they stay in step.

```tsx
const store = createColorStore({ h: 220, s: 75, v: 80, a: 1 });

<ChromaPanel store={store} />
<ColorInput store={store} />
```

See [useColorStore](/react/utils/use-color-store).

---

# Forms

Source: /react/handbook/forms

Give it a `name` and it submits with the form, responds to `form.reset()`, and
participates in native validation.

<ComponentPreview name="color-input-form-demo" />

```tsx
<form onSubmit={handleSubmit}>
  <ColorInput name="brand" defaultValue="#cc3366" required />
  <button type="submit">Save</button>
</form>
```

The submitted value is the string in whichever `format` you set, so a form that
needs `rgba()` gets it without a conversion step on your side.

## Validation

`required` marks the control invalid while it is empty. `validationBehavior`
chooses between the browser's own bubble and an ARIA-only message:

```tsx
<ColorInput name="brand" required validationBehavior="aria" />
```

## Resetting

`form.reset()` returns the control to `defaultValue`, like any native input. A
controlled `ColorInput` is yours to reset — the form cannot change state you own.

## API reference

### Props

<PropsTable name="ColorInput" />

---

# Controlled and uncontrolled

Source: /react/handbook/controlled

## Uncontrolled

The default. Pass `defaultValue` and let the panel keep the value:

```tsx
<ColorInput defaultValue="#3366cc" onChangeComplete={(c) => save(c.hex)} />
```

## Controlled

You own it. Pass `value` and update it yourself:

```tsx
const [color, setColor] = useState("#3366cc");

<ColorInput value={color} onChange={(c) => setColor(c.hex)} />;
```

<Callout variant="warning">
  Pass `value` and you must handle `onChange`, or the panel will not move.
</Callout>

## Everything else works the same way

`mode`, `open`, `collapsed`, `size` and `recentColors` all follow the same
pattern: pass the prop to control it, leave it out to let the panel manage it.

| Controlled     | Uncontrolled          | Change event                   |
| -------------- | --------------------- | ------------------------------ |
| `value`        | `defaultValue`        | `onChange`, `onChangeComplete` |
| `mode`         | `defaultMode`         | `onModeChange`                 |
| `open`         | `defaultOpen`         | `onOpenChange`                 |
| `collapsed`    | `defaultCollapsed`    | `onCollapsedChange`            |
| `size`         | `defaultSize`         | `onSizeChange`                 |
| `recentColors` | `defaultRecentColors` | `onRecentColorsChange`         |

## onChange vs onChangeComplete

`onChange` fires about 60 times a second while you drag. `onChangeComplete`
fires once, when you let go.

Use `onChange` for live preview, and `onChangeComplete` for anything that costs
something: saving, undo entries, network calls.

<Callout variant="warning" title="Do not put onChange into global state">
  It fires on every frame of a drag. Keep that state local, or save from
  `onChangeComplete` instead.
</Callout>

---

# Server rendering

Source: /react/handbook/server-rendering

Next.js App Router, Remix and other SSR setups need no special handling.

Every file that needs the browser carries `'use client'`, so you can import from
a server component without marking your own file.

The first render emits the color as CSS custom properties, so there is no flash
before hydration.

Nothing is read from `window` at module scope. `injectStyles` is a no-op when
`document` is undefined.

## Avoiding the unstyled flash

The panel injects its stylesheet from an effect, which means server-rendered
markup is unstyled until hydration. Import the stylesheet yourself and turn
injection off:

```tsx
// app/layout.tsx
import "chroma-panel/style.css";
```

```tsx
<ChromaPanel injectStyles={false} />
```

See [styling with Tailwind](/react/handbook/tailwind) for where that import has
to sit relative to your own CSS.

## Tree shaking

Importing `chroma-panel` registers all five modes through side effects listed in
the package's `sideEffects` field. If you import a mode entry point directly,
import it for its side effect rather than a binding:

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/wheel";
```

---

# Browser support

Source: /react/handbook/browser-support

|               | Minimum |
| ------------- | ------- |
| Chrome / Edge | 123     |
| Firefox       | 120     |
| Safari        | 17.5    |

Below those the CSS does not apply and the panel renders unstyled. It also uses
`:has()`, `@layer`, `color-mix()` and `svh`, all of which landed earlier than
`light-dark()`, so that one sets the floor.

## The eyedropper

Uses the browser's `EyeDropper` API, which today means Chromium.
`showEyedropper` defaults to `true`, but the button only renders where the API
exists, so nothing breaks elsewhere.

If you build your own, check `useEyedropper().supported` first — see
[useEyedropper](/react/utils/use-eyedropper).

## Image sampling

Needs `createImageBitmap` and `OffscreenCanvas`. Both are in every browser that
clears the table above.

## On a phone

Below 640px the popover becomes a bottom sheet: full width, rounded top, grab
handle, and a scrim with the page locked behind it. Controls stay compact for a
mouse and grow to a 44px hit area for touch. Pass `sheetOnMobile={false}` if you
want an anchored popover at every width instead.

There is one line a library cannot add for you:

```html
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, viewport-fit=cover"
/>
```

Without `viewport-fit=cover` the sheet will not clear the home indicator on a
notched iPhone. Everything still works, it just sits a little low.

---

# TypeScript

Source: /react/handbook/typescript

## The types you will reach for

```ts
import type {
  ColorChangeResult,
  ColorFormat,
  Hsva,
  Rgba,
  ColorPalette,
  ModeId,
  PickerMode,
} from "chroma-panel";
```

## ColorChangeResult

What every change handler receives. Every field is always present, whatever you
set `format` to, so you can read `hex` and `rgba` regardless.

```ts
type ColorChangeResult = {
  hex: string;
  hexa: string;
  rgb: Rgb;
  rgba: Rgba;
  hsl: Hsl;
  hsla: Hsla;
  hsva: Hsva;
  css: string;
};
```

`css` is the string in whichever `format` you chose, and the value a form
submits.

## Typing a handler

```tsx
import { ColorInput, type ColorChangeResult } from "chroma-panel";

function handleChange(result: ColorChangeResult): void {
  console.log(result.hex, result.hsva);
}

<ColorInput onChange={handleChange} />;
```

## Prop types

Both component prop interfaces are exported, so you can extend them:

```ts
import type { ChromaPanelProps, ColorInputProps } from "chroma-panel";

type BrandPickerProps = ColorInputProps & { label: string };
```

`ColorInputProps` extends `ChromaPanelProps`, so everything the panel takes,
the input takes too.

---

# Common mistakes

Source: /react/handbook/common-mistakes

## Putting onChange into global state

It fires about 60 times a second while you drag. Keep that state local, or save
from `onChangeComplete` instead — see
[onChange vs onChangeComplete](/react/handbook/controlled#onchange-vs-onchangecomplete).

## Expecting injectStyles={false} to shrink your bundle

It only stops the panel writing a `<style>` tag. The CSS is imported by the
module either way, so your build is the same size. Use it for CSP or critical
CSS.

## An unlayered button rule in your own CSS

It will restyle the panel's swatches and tabs. This is the most common cause of a
panel that looks almost right — see
[if the panel looks wrong](/react/handbook/theming#if-the-panel-looks-wrong).

## Expecting the eyedropper everywhere

It renders only where the browser has the `EyeDropper` API. If you need one in
every browser, build your own UI and check `useEyedropper().supported` first.

## Reading hex when you need precision

`hex` is rounded to 8 bits per channel. Store `hsva` and pass it back to `value`
if a color has to survive a round trip unchanged.

---

# ColorInput

Source: /react/components/color-input

## Anatomy

```tsx
import { ColorInput } from "chroma-panel";

<ColorInput defaultValue="#3366cc" onChangeComplete={(c) => save(c.hex)} />;
```

`ColorInput` takes every prop `ChromaPanel` takes, plus the popover and form
props below. It also drops into a form like an `<input>` — see
[forms](/react/handbook/forms).

## Demo

<ComponentPreview name="color-input-demo" />

## API reference

### Props

<PropsTable name="ColorInput" />

---

# ChromaPanel

Source: /react/components/chroma-panel

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel";

<ChromaPanel defaultValue="#3366cc" modes={["wheel"]} showTitleBar={false} />;
```

## Demo

<ComponentPreview name="chroma-panel-demo" />

## API reference

### Props

<PropsTable name="ChromaPanel" />

---

# Popover

Source: /react/components/popover

## Anatomy

```tsx
import { Popover } from "chroma-panel";
```

Below 640px it becomes a bottom sheet. Pass `sheetOnMobile={false}` for an
anchored popover at every width.

## API reference

### Props

<PropsTable name="Popover" />

---

# ModeToolbar

Source: /react/components/mode-toolbar

## Anatomy

```tsx
import { ModeToolbar } from "chroma-panel";
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="ModeToolbar" />

---

# PanelFooter

Source: /react/components/panel-footer

## Anatomy

```tsx
import { PanelFooter, pushRecent } from "chroma-panel";
```

The footer shows the current colour once, alongside the recent-colour history.
The history row fades on whichever side has more swatches.

## Adding to the history yourself

<Signature name="pushRecent" />

Turn the row off entirely with `showRecentColors={false}` on the panel, or
control it with `recentColors` and `onRecentColorsChange` — see
[controlled and uncontrolled](/react/handbook/controlled).

---

# ColorArea

Source: /react/components/color-area

## Anatomy

```tsx
import { ColorArea } from "chroma-panel";

<ColorArea height={180} />;
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="ColorArea" />

---

# ColorDisc

Source: /react/components/color-disc

## Anatomy

```tsx
import { ColorDisc } from "chroma-panel";

<ColorDisc />;
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="ColorDisc" />

---

# ChannelSlider

Source: /react/components/channel-slider

## Anatomy

```tsx
import { ChannelSlider } from "chroma-panel";

<ChannelSlider
  label="Hue"
  min={0}
  max={360}
  read={(c) => c.h}
  write={(h, c) => ({ ...c, h })}
/>;
```

Keyboard handling and screen-reader announcements come from the browser, because
the track is a real `<input type="range">`.

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="ChannelSlider" />

---

# ColorField

Source: /react/components/color-field

## Anatomy

```tsx
import { ColorField } from "chroma-panel";

<ColorField label="Hex" withAlpha />;
```

See [parsing](/react/utils/parsing) for what it accepts.

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="ColorField" />

---

# NumberField

Source: /react/components/number-field

## Anatomy

```tsx
import { NumberField } from "chroma-panel";
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="NumberField" />

---

# Swatch

Source: /react/components/swatch

## Anatomy

```tsx
import { Swatch } from "chroma-panel";
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="Swatch" />

---

# SwatchGrid

Source: /react/components/swatch-grid

## Anatomy

```tsx
import { SwatchGrid } from "chroma-panel";
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="SwatchGrid" />

---

# SegmentedControl

Source: /react/components/segmented-control

## Anatomy

```tsx
import { SegmentedControl } from "chroma-panel";
```

<Callout variant="note" title="Only inside a panel">
  This is one of the parts the built-in modes are made of. It reads the colour
  through `usePanel()`, so it only works inside a `ChromaPanel` — typically in a
  [custom mode](/react/modes/custom). For a picker outside the panel, use [the
  store and hooks](/react/utils/use-color-store).
</Callout>

## API reference

### Props

<PropsTable name="SegmentedControl" />

---

# Wheel

Source: /react/modes/wheel

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/wheel";

<ChromaPanel modes={["wheel"]} />;
```

The disc is sized by `--cp-disc-size`, and grows when the panel is widened with
the green window control.

## Demo

<ComponentPreview name="chroma-panel-wheel-demo" />

## Mode id

`'wheel'`. List it in `modes` to show the tab, and in the order you want the tabs.

---

# Sliders

Source: /react/modes/sliders

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/sliders";

<ChromaPanel modes={["sliders"]} />;
```

Each row is a [ChannelSlider](/react/components/channel-slider) backed by a real
`<input type="range">`, so keyboard and screen-reader behaviour come from the
browser.

## Mode id

`'sliders'`. List it in `modes` to show the tab, and in the order you want the tabs.

---

# Palettes

Source: /react/modes/palettes

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/palettes";

<ChromaPanel
  modes={["palettes"]}
  palettes={[{ name: "Brand", colors: ["#3366cc", "#cc3366"] }]}
/>;
```

Leave `palettes` out to get the built-in set. Read it with `defaultPalettes` if
you want to extend rather than replace it.

## Mode id

`'palettes'`. List it in `modes` to show the tab, and in the order you want the tabs.

---

# Image

Source: /react/modes/image

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/image";

<ChromaPanel modes={["image"]} imageOptions={{ maxColors: 12 }} />;
```

Large images are downscaled before they are read, so a 4000x3000 photo never
loads in full. A loaded image stays put when you close and reopen the picker, and
is released when you replace it, remove it, or leave the page.

`imageOptions` is shorthand. These two are the same:

```tsx
<ChromaPanel imageOptions={{ maxColors: 12 }} />
<ChromaPanel modeProps={{ image: { extractOptions: { maxColors: 12 } } }} />
```

Sampling takes a few milliseconds, so it runs on the main thread. If you raise
`size` a lot, move it to a worker. Build the URL in your own source so your
bundler resolves it:

```ts
const url = new URL("chroma-panel/image-worker", import.meta.url);
const worker = new Worker(url, { type: "module" });

await extractPalette(file, { size: 400, worker });
```

## API reference

<SignatureList names="extractPalette, quantize" />

## Mode id

`'image'`. List it in `modes` to show the tab, and in the order you want the tabs.

---

# Pencils

Source: /react/modes/pencils

## Anatomy

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/pencils";

<ChromaPanel modes={["pencils"]} pencils={myColors} />;
```

Leave `pencils` out for the built-in 120-colour grid, or read it from
`defaultPencils`.

## Mode id

`'pencils'`. List it in `modes` to show the tab, and in the order you want the tabs.

---

# Custom modes

Source: /react/modes/custom

## Registering

```tsx
import { registerMode, ChromaPanel } from "chroma-panel";

registerMode({
  id: "brand",
  label: "Brand colors",
  icon: BrandIcon,
  Panel: BrandPanel, // reads the color with usePanel()
});

<ChromaPanel modes={["wheel", "brand"]} />;
```

Inside `BrandPanel`, reach the colour with
[`usePanel()`](/react/utils/use-color-store), and use the panel's own controls —
[ColorArea](/react/components/color-area),
[Swatch](/react/components/swatch) and the rest.

## Passing props into a mode

`modeProps` is keyed by mode id, and each entry is spread onto that mode's panel
component. It exists so a custom mode can take props without the panel needing
to know about it:

```tsx
<ChromaPanel modeProps={{ brand: { team: "design" } }} />
```

## API reference

<SignatureList names="registerMode, getMode, resolveModes" />

---

# Color engine

Source: /react/utils/color-engine

The engine is a separate entry point, so you can use it without pulling in any
React:

```ts
import { parse, toFormat, ingest } from "chroma-panel/core";
```

## Why HSVA is the internal model

HSV has two places where information disappears. At zero saturation there is no
hue to speak of, and at zero brightness there is neither. Keeping state as RGB or
hex loses the hue you picked the moment brightness hits zero.

The engine keeps the full HSVA value and merges changes into it, so dragging to
an extreme and back returns the colour you started with. See
[about](/react/overview/about).

## Where to go next

- [Parsing](/react/utils/parsing) — strings in
- [Serializing](/react/utils/serializing) — strings out
- [Converting](/react/utils/converting) — between models
- [Contrast](/react/utils/contrast) — APCA and WCAG helpers

---

# Parsing

Source: /react/utils/parsing

```ts
import { parse, isValidColor } from "chroma-panel";

parse("#3366cc");
parse("rgb(51 102 204)");
parse("hsl(220 60% 50%)");
parse("hwb(220 20% 20%)");

isValidColor("not a colour"); // false
```

Hex (3, 4, 6 and 8 digit), `rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()` and the
modern space-separated forms are all accepted.

## API reference

<SignatureList names="parse, isValidColor" />

## Merging rather than replacing

`ingest` is what the panel uses internally. It merges a change into a full HSVA
value instead of replacing it, which is what preserves hue and saturation at the
extremes — see [converting](/react/utils/converting).

<Signature name="ingest" />

## Named colors

`parse("rebeccapurple")` returns null until you register the names. They cost
about 1.3 kB gzipped, so they are opt-in — see
[named colors](/react/utils/named-colors).

---

# Serializing

Source: /react/utils/serializing

```ts
import { toFormat } from "chroma-panel";

toFormat(hsva, "hex"); // '#3366cc'
toFormat(hsva, "rgba"); // 'rgba(51, 102, 204, 1)'
toFormat(hsva, "hsl"); // 'hsl(220, 60%, 50%)'
```

The formats are `'hex'`, `'hexa'`, `'rgb'`, `'rgba'`, `'hsl'` and `'hsla'`. This
is the same conversion behind the `format` prop, which sets the `css` field on a
change result and the value a form submits.

## API reference

<Signature name="toFormat" />

### One format at a time

Each format has its own function, if you know which you want.

<SignatureList names="toHex, toHexa, toRgbString, toRgbaString, toHslString, toHslaString" />

### Every format at once

<Signature name="toResult" />

<Callout variant="note" title="Precision">
  `hex` is rounded to 8 bits per channel. Keep the `hsva` if a colour has to
  survive a round trip unchanged.
</Callout>

---

# Converting

Source: /react/utils/converting

```ts
import { hsvaToRgba, hsvaToHsla, hslaToHsva } from "chroma-panel";
```

## API reference

<SignatureList names="hsvaToRgba, rgbaToHsva, hsvaToHsla, hslaToHsva, hsvaToHwba, hwbaToHsva" />

## Keeping hue and saturation

HSV has two places where information disappears. At zero saturation there is no
hue to speak of, and at zero brightness there is neither. Converting away from
HSVA and back loses them.

If you are round-tripping a colour through another model, keep the original HSVA
and merge into it:

<Signature name="ingest" />

## Comparing and clamping

<SignatureList names="sameHsva, clamp, normalizeHue" />

---

# Contrast

Source: /react/utils/contrast

Available without React:

```ts
import { contrastReport, readableTextColor } from "chroma-panel/contrast";
```

## Picking a text colour

```ts
readableTextColor("#001f3f"); // '#ffffff'
```

<Signature name="readableTextColor" />

## Checking a pair

<SignatureList names="contrastReport, contrastRatio, meetsContrast, meetsNonTextContrast, wcagLevel" />

## The underlying measures

<SignatureList names="apcaContrast, relativeLuminance" />

<Callout variant="note" title="Why APCA for text colour">
  `readableTextColor` uses APCA rather than plain luminance. It picks white over
  mid-blues, where the older method wrongly picks black.
</Callout>

---

# Named colors

Source: /react/utils/named-colors

```ts
import { registerNamedColors } from "chroma-panel";
import { namedColors } from "chroma-panel/named-colors";

registerNamedColors(namedColors);
```

Now `parse('rebeccapurple')` works, and so does typing a name into
[ColorField](/react/components/color-field).

## API reference

<SignatureList names="registerNamedColors, clearNamedColors" />

## Registering your own

The registry takes any map of name to colour string, so you can register a brand
vocabulary instead of, or alongside, the CSS names:

```ts
registerNamedColors({ brand: "#3366cc", "brand-dark": "#254a91" });
```

---

# useColorStore

Source: /react/utils/use-color-store

```ts
import { createColorStore } from "chroma-panel/core";

const store = createColorStore({ h: 220, s: 75, v: 80, a: 1 });
```

`chroma-panel/core` has no React and no DOM, so the store can live in code that
runs anywhere.

## API reference

<Signature name="createColorStore" />

| Method                                  | Does                                          |
| --------------------------------------- | --------------------------------------------- |
| `get()`                                 | Current `Hsva`                                |
| `set(next)`                             | Replace the colour                            |
| `patch(partial)`                        | Change some channels                          |
| `ingest(next)`                          | Merge, keeping hue and saturation             |
| `commit()`                              | Mark the end of a gesture                     |
| `subscribe(fn)`                         | Every change. Returns an unsubscribe function |
| `subscribeCommit(fn)`                   | Only on commit                                |
| `getSnapshot()` / `getServerSnapshot()` | For `useSyncExternalStore`                    |

`subscribe` fires on every frame of a drag. `subscribeCommit` fires once when the
gesture ends. That split is what `onChange` and `onChangeComplete` are built on.

## Reading it in React

<SignatureList names="useColorValue, useTransientColor, usePanel" />

`useTransientColor` is how the panel stays smooth. It writes to the DOM directly
instead of setting state:

```tsx
useTransientColor(store, (c) => {
  el.current.style.background = toHex(c);
});
```

## Building a control of your own

<SignatureList names="usePointerDrag, useAxisKeyboard" />

## Driving several panels

Pass a store to `ColorInput` or `ChromaPanel` with the `store` prop to drive
several components from one value.

```tsx
<ChromaPanel store={store} />
<ColorInput store={store} />
```

---

# useEyedropper

Source: /react/utils/use-eyedropper

```tsx
import { useEyedropper } from "chroma-panel";

function PickFromScreen() {
  const { supported, pick } = useEyedropper();

  if (!supported) {
    return null;
  }

  return <button onClick={() => pick().then(setColor)}>Pick</button>;
}
```

## API reference

<Signature name="useEyedropper" />

<Callout variant="warning" title="Not everywhere">
  This wraps the browser's `EyeDropper` API, which today means Chromium. Always
  check `supported` before rendering your own trigger.
</Callout>

The panel's own eyedropper button does this check for you: `showEyedropper`
defaults to `true`, but the button only renders where the API exists. See
[browser support](/react/handbook/browser-support).

---

# Entry points

Source: /react/utils/entry-points

Importing `chroma-panel` registers all five modes. Import the shell and add modes
yourself to cut that down.

```tsx
import { ChromaPanel } from "chroma-panel/panel";
import "chroma-panel/wheel";

<ChromaPanel modes={["wheel"]} />;
```

| What you import     | Added to your app |
| ------------------- | ----------------- |
| all five modes      | 22.2 kB           |
| shell plus one mode | 14.1 kB           |

## The subpaths

| Entry point                 | What it holds                              |
| --------------------------- | ------------------------------------------ |
| `chroma-panel`              | Everything, with all five modes registered |
| `chroma-panel/panel`        | The panel shell, no modes                  |
| `chroma-panel/core`         | The colour engine, no React                |
| `chroma-panel/wheel`        | The wheel mode                             |
| `chroma-panel/sliders`      | The sliders mode                           |
| `chroma-panel/palettes`     | The palettes mode                          |
| `chroma-panel/image`        | The image mode                             |
| `chroma-panel/pencils`      | The pencils mode                           |
| `chroma-panel/named-colors` | The 148 CSS colour names                   |
| `chroma-panel/contrast`     | APCA and WCAG helpers                      |
| `chroma-panel/image-worker` | The worker for off-thread sampling         |
| `chroma-panel/style.css`    | The stylesheet                             |

<Callout variant="note" title="Import modes for the side effect">
  A mode entry point registers itself. Write `import "chroma-panel/wheel"`, not
  a named import, or a bundler may drop it.
</Callout>

---