# Color Picker

> A color picker with a saturation and brightness area, hue and alpha sliders, a hex field and swatches.

`<slab-color-picker>` · Form · built on `[role=slider]`

## Install

```sh
pnpm add slab-elements lit
```

## Usage

```html
<script type="module">
  import 'slab-elements/color-picker.js';
</script>

<slab-color-picker label="Fill" name="fill" value="#3399ff" swatches="#ff0000 #00ff00 #0000ff" alpha></slab-color-picker>
```

## Example

Here's a styled version, `<slab-styled-color-picker>`. It's not in the package — it's an example of what you can build with the headless element. Copy it and make it yours at the bottom of this page.

```html
<slab-styled-color-picker label="Stain" value="#8a5a3c" swatches="#8a5a3c #a0522d #6b6b6b #3f4a3c #c2b280">
  <span slot="description">Acid stain reacts with the lime in the slab, so the cured color varies.</span>
</slab-styled-color-picker>
```

Swap `slab-styled-` for `slab-` in that markup and you've got the same example as it ships: the headless elements with no CSS at all. That's your starting point.

The area, the hue slider and the alpha slider are each a `[role=slider]`, named by `label` and then their own label, so a screenreader reads "Fill Hue". The area's value text reads both of its values, "Saturation 60%, Brightness 100%". Give the area and the sliders a size, since their thumbs are placed along them. The form gets `value` under `name`.

The hex field commits when it's blurred or Enter is pressed, with or without the "#", and goes back to `value` when what's typed isn't a color. The swatches are a listbox whose selection follows focus.

## Keyboard

| Key                   | What it does                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------- |
| Left, Right           | In the area, steps saturation. On a slider, steps it. Each moves the thumb the way it points. |
| Down, Up              | In the area, steps brightness. On a slider, steps it.                                         |
| Page Up, Page Down    | In the area, steps brightness by 10. On a slider, steps it by a tenth.                        |
| Home, End             | In the area, moves saturation to 0 or 100. On a slider, moves it to either end.               |
| Left, Down, Right, Up | In the swatches, moves to the previous or next swatch and selects it.                         |
| Home, End             | In the swatches, moves to the first or last swatch and selects it.                            |
| Enter                 | In the hex field, commits it.                                                                 |

## Behavior

A color picker with no visual styles: a two-dimensional area for saturation and brightness, a hue slider, an optional alpha slider, a hex field, and optional swatches.

`value` is a lowercase hex color, "#rrggbb", or "#rrggbbaa" with `alpha` when the color isn't opaque, as a native color input's is. It takes "#rgb" and "#rgba" too, and anything else is taken as "#000000", as a native color input takes it. Like a native input's `value`, the attribute is the default and the property is the current value.

The area is a `[role=slider]` whose value is its saturation and whose value text is its saturation and brightness. Left and Right change saturation, and Up and Down change brightness. The hue and alpha sliders are `[role=slider]`s as well. Each is named by `label` and its own label, so a screenreader reads "Fill Hue". The arrow keys step by one, Page Up and Page Down by a tenth, and Home and End go as far as they can. Drag a thumb, or press anywhere along a slider or the area to move it there.

The hex field commits on "change", when it's blurred or Enter is pressed, and goes back to `value` when what's typed isn't a color. `swatches` is a space-separated list of colors, shown as a listbox whose selected option is the swatch that's `value`. Selection follows focus.

What makes a color picker a color picker is functional, so that's done here: the area is the hue from white to fully saturated, darkening toward black. The hue slider is the spectrum, the alpha slider is clear to opaque, and each thumb and swatch is placed and colored. Give the area and the sliders a size, and style the rest through its parts and through `:state(disabled)` and `:state(dragging)`. The container sets `--color-picker-hue`, `--color-picker-opaque` and `--color-picker-value`, and each swatch `--color-picker-swatch`, for styles of your own.

## API

### `<slab-color-picker>`

#### Attributes

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Names the group. Each control is named by it and its own label. |
| `alpha` | `boolean` | `false` | Adds the alpha slider, and `value` is "#rrggbbaa" when the color isn't opaque. |
| `alpha-label` | `string` |  | Names the alpha slider, after `label`. "Alpha" when unset. |
| `area-label` | `string` |  | Names the area, after `label`. "Saturation and brightness" when unset. |
| `brightness-label` | `string` |  | Read before the area's brightness. "Brightness" when unset. |
| `disabled` | `boolean` | `false` |  |
| `hex-label` | `string` |  | Names the hex field, after `label`. "Hex" when unset. |
| `hide-label` | `boolean` | `false` |  |
| `hue-label` | `string` |  | Names the hue slider, after `label`. "Hue" when unset. |
| `name` | `string` | `''` |  |
| `saturation-label` | `string` |  | Read before the area's saturation. "Saturation" when unset. |
| `swatches` | `string` | `''` | Space-separated colors to pick from. Ones that aren't colors are left out. |
| `swatches-label` | `string` |  | Names the swatches, after `label`. "Swatches" when unset. |
| `value` | `string` | `'#000000'` | Like a native input's `value`, the attribute is the default and the property is the current value. "#000000" when unset. |
| `version` | `string` |  |  |

#### Properties

| Name | Type | Description |
| --- | --- | --- |
| `form` (read-only) | `HTMLFormElement \| null` |  |
| `validity` (read-only) | `ValidityState` |  |

#### Methods

| Signature | Description |
| --- | --- |
| `checkValidity(): boolean` |  |
| `focus(options?: FocusOptions): void` |  |
| `reportValidity(): boolean` |  |

#### Events

| Name | Type | Description |
| --- | --- | --- |
| `input` | `Event` |  |
| `change` | `Event` |  |

#### Slots

| Name | Type | Description |
| --- | --- | --- |
| `description` | `Element \| string` | Text about the color picker, such as a hint |

#### CSS parts

| Name | Description |
| --- | --- |
| `alpha` | The alpha slider's track |
| `alpha-thumb` | The alpha slider's thumb |
| `area` | The saturation and brightness area |
| `area-thumb` | The area's thumb |
| `container` | The label, the controls and the description |
| `description` | Text about the color picker, such as a hint |
| `hex` |  |
| `hue` | The hue slider's track |
| `hue-thumb` | The hue slider's thumb |
| `label` | The label |
| `selected` | The swatch that's value |
| `swatch` | A swatch |
| `swatches` | The swatches |

## Copy and own it

`<slab-styled-color-picker>` isn't in the package. It's an example — copy it into your project and change whatever you want. Under the hood, it's just the headless element, subclassed, with `styles` set. That's it. Keyboard, focus, ARIA, forms, and events all come from the headless element, and the styles only reach in through `::part()` and `:state()`, same as yours would.

To use it, copy these files, swap the tag in `@customElement()` for one of your own, and import it. `tokens.styles.ts` holds the colors and fonts every styled example shares, so you only need it once.

### TypeScript

These files are TypeScript, and `@customElement()` is one of Lit's decorators (TypeScript's experimental flavor). You'll need two options in your tsconfig, per [Lit's docs](https://lit.dev/docs/components/decorators/#decorators-typescript): `experimentalDecorators` to compile them, and `useDefineForClassFields` turned off so class fields don't stomp on the accessors Lit sets up.

```json
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false
  }
}
```

Using plain JavaScript? Drop the types and register the class with `customElements.define()` instead of the decorator.

### color-picker.ts

```ts
import { customElement } from 'lit/decorators.js';
import ColorPicker from 'slab-elements/color-picker.js';
import styles from './color-picker.styles.js';
import tokens from './tokens.styles.js';

declare global {
  interface HTMLElementTagNameMap {
    'slab-styled-color-picker': StyledColorPicker;
  }
}

/**
 * Color Picker, styled: a bordered area and sliders with Range Slider's
 * brick-shaped thumbs, filled with the color they're on, and square swatches.
 */
@customElement('slab-styled-color-picker')
export default class StyledColorPicker extends ColorPicker {
  static override styles = [tokens, styles];
}
```

### color-picker.styles.ts

```ts
import { css } from 'lit';

/*
  The thumbs are centered on their values, so at either end of a track half
  of one hangs off it. The area and the sliders are inset by half a thumb so
  they stay inside the host. A checkerboard sits under the alpha slider's
  gradient and the swatches, so a clear color reads as clear.
*/
export default css`
  :host {
    --checkerboard: repeating-conic-gradient(
        var(--chalk) 0 25%,
        var(--paper) 0 50%
      )
      0 0 / 0.75rem 0.75rem;

    color: var(--ink);
    display: grid;
    font-family: var(--font-body);
    max-inline-size: 20rem;
  }

  [part~='container'] {
    display: grid;
    gap: 0.75rem;
  }

  [part~='label'] {
    font-family: var(--font-display);
    font-size: 1.0625rem;
    font-weight: 600;
  }

  [part~='area'],
  [part~='hue'],
  [part~='alpha'] {
    border: var(--border);
    box-sizing: border-box;
    cursor: pointer;
    margin-inline: 0.5rem;
  }

  [part~='area'] {
    block-size: 10rem;
  }

  [part~='hue'],
  [part~='alpha'] {
    block-size: 0.875rem;
    margin-block: 0.5rem;
  }

  [part~='alpha'] {
    background:
      linear-gradient(to right, transparent, var(--color-picker-opaque)),
      var(--checkerboard);
  }

  :host(:dir(rtl)) [part~='alpha'] {
    background:
      linear-gradient(to left, transparent, var(--color-picker-opaque)),
      var(--checkerboard);
  }

  [part~='area-thumb'],
  [part~='hue-thumb'],
  [part~='alpha-thumb'] {
    background-color: var(--color-picker-opaque);
    border: 2px solid var(--paper);
    box-shadow: 0 0 0 2px var(--ink);
    box-sizing: border-box;

    &:focus-visible {
      outline: 3px solid var(--ember);
      outline-offset: 3px;
    }
  }

  [part~='area-thumb'] {
    block-size: 1.25rem;
    inline-size: 1.25rem;
  }

  [part~='hue-thumb'],
  [part~='alpha-thumb'] {
    block-size: 1.875rem;
    inline-size: 1rem;
  }

  [part~='hue-thumb'] {
    background-color: hsl(var(--color-picker-hue) 100% 50%);
  }

  [part~='hex'] {
    background-color: var(--paper);
    block-size: 3rem;
    border: var(--border);
    border-radius: 0;
    box-sizing: border-box;
    color: inherit;
    font-family: var(--font-mono);
    font-size: 1rem;
    padding: 0 0.75rem;

    &:focus-visible {
      box-shadow: 4px 4px 0 var(--ember);
      outline: 2px solid transparent;
    }

    &:disabled {
      background-color: var(--chalk);
      border-style: dashed;
      color: var(--ash);
      cursor: not-allowed;
    }
  }

  [part~='swatches'] {
    display: flex;
    flex-wrap: wrap;
    gap: 0.5rem;
  }

  [part~='swatch'] {
    background:
      linear-gradient(var(--color-picker-swatch), var(--color-picker-swatch)),
      var(--checkerboard);
    block-size: 2rem;
    border: var(--border);
    box-sizing: border-box;
    cursor: pointer;
    inline-size: 2rem;

    &:focus-visible {
      outline: 3px solid var(--ember);
      outline-offset: 2px;
    }
  }

  [part~='selected'] {
    box-shadow:
      inset 0 0 0 2px var(--paper),
      0 0 0 2px var(--ink);
  }

  [part~='description'] {
    color: var(--ash);
    display: block;
    font-size: 0.875rem;
  }

  :host(:state(disabled)) [part~='container'] {
    cursor: not-allowed;
    opacity: 0.5;
  }

  :host(:state(disabled)) [part~='area'],
  :host(:state(disabled)) [part~='hue'],
  :host(:state(disabled)) [part~='alpha'],
  :host(:state(disabled)) [part~='swatch'] {
    cursor: not-allowed;
  }
`;
```

### tokens.styles.ts

```ts
import { css } from 'lit';

/*
  The styled components' palette and type, taken from the logo: ink for the
  courses, ember for the base, paper behind them.

  Each is a short alias for a "--slab-styled-*" property, with the default as
  its fallback. Retheming is "--slab-styled-ember" and the rest on ":root",
  which every shadow root inherits. Were the defaults declared under those
  names here instead, each host's own declaration would shadow the page's.

  Each default is "light-dark()", so the components follow the page's
  "color-scheme": "dark" for dark, "light" for light, and "light dark" to
  follow the operating system. Ink and paper trade places in the dark, so
  ink is always the text and paper always what's behind it. Contrast is given
  as light, then dark.
*/
export default css`
  :host {
    /* Secondary text. 6.8:1 and 6.9:1 on paper. */
    --ash: var(--slab-styled-ash, light-dark(#5e5a55, #a8a19a));
    --border: 2px solid var(--ink);

    /* Behind disabled and read-only controls, and hovered rows. */
    --chalk: var(--slab-styled-chalk, light-dark(#f4f1ec, #2b2926));

    /*
      The logo's orange, brighter in the dark. 4.25:1 and 5.2:1 on paper is
      enough for borders, fills and large text, but not always for small text,
      which takes "--ember-deep".
    */
    --ember: var(--slab-styled-ember, light-dark(#d9492a, #ec5f3b));

    /*
      Orange for small text on paper, and for paper text on it. 5.7:1 and
      7.4:1.
    */
    --ember-deep: var(--slab-styled-ember-deep, light-dark(#b3381a, #ff8566));
    --font-body: var(
      --slab-styled-font-body,
      'IBM Plex Sans',
      system-ui,
      sans-serif
    );
    --font-display: var(
      --slab-styled-font-display,
      'Zilla Slab',
      rockwell,
      'Roboto Slab',
      serif
    );
    --font-mono: var(
      --slab-styled-font-mono,
      'IBM Plex Mono',
      ui-monospace,
      monospace
    );
    --ink: var(--slab-styled-ink, light-dark(#1c1c1c, #f4f1ec));
    --paper: var(--slab-styled-paper, light-dark(#fff, #1a1918));

    /* The hard, offset shadow a raised surface casts. */
    --shadow: 4px 4px 0 var(--ink);
  }
`;
```