Color Picker

# Color Picker

```astro
---
import { ColorPicker } from "@/components/starwind/color-picker";
---

<ColorPicker />
```

## Installation

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

## Usage

### General Notes

`ColorPicker` uses a hidden native color input trigger and a custom floating picker panel for selecting hue, saturation, and opacity. It supports HEX/RGB/HSL/HSB formatting in the panel and emits a custom change event when values update.

### Sizes

Use the `size` prop to switch between `"sm"`, `"md"`, and `"lg"` variants.

```astro
---
import { ColorPicker } from "@/components/starwind/color-picker";
---

<ColorPicker size="sm" />
<ColorPicker size="md" />
<ColorPicker size="lg" />
```

### Default Value

Pass `defaultValue` as a hex color string to initialize the picker with a specific color.

```astro
---
import { ColorPicker } from "@/components/starwind/color-picker";
---

<ColorPicker defaultValue="#ff0000" />
```

### Programmatic Set Value

Call the element's `setValue` method with `rgb(r,g,b)` or `rgba(r,g,b,a)` to update the picker programmatically.

> **Tip:** Open the browser console and click the button to see the emitted value from the `starwind-color-picker:change` event.

```astro
---
import { Button } from "@/components/starwind/button";
import { ColorPicker } from "@/components/starwind/color-picker";
---

<ColorPicker id="color-picker-programmatic" />
<Button size="sm" variant="primary" class="mt-4" id="programmatic-set-value-btn">
  Programmatically select color rgb(0,0,255)
</Button>

<script>
  import type { ColorPickerChangeEvent } from "@/components/starwind/color-picker/ColorPickerTypes";

  type ProgrammaticColorPickerElement = HTMLElement & {
    setValue: (newRgb: string) => void;
  };

  const colorPickerProgrammatic = document.getElementById(
    "color-picker-programmatic",
  ) as ProgrammaticColorPickerElement | null;
  const programmaticBtn = document.getElementById("programmatic-set-value-btn");

  if (colorPickerProgrammatic && programmaticBtn) {
    programmaticBtn.addEventListener("click", () => {
      colorPickerProgrammatic.setValue("rgb(0,0,255)");
    });

    colorPickerProgrammatic.addEventListener("starwind-color-picker:change", (event: Event) => {
      console.log("selectedValue: ", (event as ColorPickerChangeEvent).detail.value);
    });
  }
</script>
```

### Custom Use

Because `ColorPicker` renders as a compact interactive control, you can compose it into custom UI patterns like icon-based toolbars.

```astro
---
import TextColor from "@tabler/icons/outline/text-color.svg";

import { ColorPicker } from "@/components/starwind/color-picker";
---

<span
  class="dark:bg-input/30 bg-background flex h-11 w-11 flex-col items-center justify-center gap-px rounded-md border px-2"
>
  <TextColor class="size-4" />
  <ColorPicker class="h-3 w-8" defaultValue="#ff0000" />
</span>
```

## API Reference

### ColorPicker

A compact color selection control with a floating advanced picker.

| Prop | Type | Default |
|------|------|---------|
| `defaultValue` | `string` | `"#000000"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `class` | `string` | - |
| `id` | `string` | - |
| `name` | `string` | - |
| `disabled` | `boolean` | `false` |
| `required` | `boolean` | `false` |
| `readonly` | `boolean` | `false` |

```astro
<ColorPicker defaultValue="#2563eb" size="md" />
```

**Additional Notes:**
- Supports additional standard input attributes such as `autocomplete`, `form`, `min`, `max`, `step`, and `title`
- Supports `aria-*` attributes for accessibility metadata
- The root element exposes a `setValue("rgb(r,g,b)")` method for programmatic updates
- Emits `starwind-color-picker:change` with detail `{ value: string, selectId: string }`