# ch-color-picker

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Use when](#use-when)
- [Do not use when](#do-not-use-when)
- [Accessibility](#accessibility)
- [Usage](./usage.md)
- [Properties](#properties)
- [Events](#events)
- [Dependencies](#dependencies)
  - [Depends on](#depends-on)
  - [Graph](#graph)
- [Styling](./styling.md)

<!-- Auto Generated Below -->

## Overview

The `ch-color-picker` component is a full-featured color selection control that lets users pick colors using a color field, hue slider, and optional alpha slider

## Features
 - Two-dimensional color field for saturation and brightness selection
 - Hue slider and optional alpha (opacity) slider
 - Multiple color formats: HEX, RGB, HSL, and HSV
 - Built-in format selector for switching formats at runtime
 - Configurable palette of preset colors
 - Form-associated via `ElementInternals`

## Use when
 - Precise color input is required in design tools or theming panels
 - Users need to switch between color formats
 - A color palette with preset colors is needed alongside free-form selection
 - Allowing users to select arbitrary colors in design or customization UIs

## Do not use when
 - Only a predefined set of colors is needed — prefer `ch-combo-box-render` with color swatches instead
 - A small curated set of colors is sufficient — use color swatches or tiles instead, which are more scannable and accessible
 - Color alone is used to convey meaning downstream — always supplement with text or pattern (WCAG 1.4.1)

## Accessibility
 - Form-associated via `ElementInternals` — participates in native form validation and submission
 - Validates label existence via `ElementInternals` for proper accessible name resolution

## Properties

| Property                  | Attribute                    | Description                                                                                                                                                                                                                                        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |   |   |
| `accessibleName`          | `accessible-name`            | Specifies a short string that authors associate with an element to provide users of assistive technologies with a label for the element.                                                                                                           | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `alphaSliderStep`         | `alpha-slider-step`          | Specifies the step size in pixels for the alpha slider. Default = 1.                                                                                                                                                                               | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `colorFieldStep`          | `color-field-step`           | Specifies the step size in pixels for keyboard navigation on the color field. Default = 1.                                                                                                                                                         | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `colorPalette`            | --                           | Array of colors to display in the color palette. Can be used for recent colors, preset colors, brand colors, or any custom palette. Accepts any valid CSS color format (hex, rgb, hsl, etc.).                                                      | `string[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `[]`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `disabled`                | `disabled`                   | This attribute lets you specify if the element is disabled. If disabled, it will not fire any user interaction related event (for example, click event).                                                                                           | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hueSliderStep`           | `hue-slider-step`            | Specifies the step size in pixels for the hue slider control. Default = 1.                                                                                                                                                                         | `number`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `1`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `order`                   | --                           | Specifies the order for the controls. Uses the CSS `order` property internally to reorder them visually. The default layout order is: colorField (1), colorPreview (2), hueSlider (3), alphaSlider (4), colorFormatSelector (5), colorPalette (6). | `{ colorField?: number; colorFormatSelector?: number; colorPreview?: number; hueSlider?: number; alphaSlider?: number; colorPalette?: number; }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `{     colorField: 1,     colorPreview: 2,     hueSlider: 3,     alphaSlider: 4,     colorFormatSelector: 5,     colorPalette: 6   }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `readonly`                | `readonly`                   | This attribute indicates that the user cannot modify the value of the control. Same as [readonly](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-readonly) attribute for `input` elements.                                   | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showAlphaSlider`         | `show-alpha-slider`          | Shows/hides the alpha (transparency) slider. Allows users to adjust color opacity from 0% (transparent) to 100% (opaque). The alpha channel value is only meaningful in the output when the selected color format supports it (RGBA, HSLA).        | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showColorFormatSelector` | `show-color-format-selector` | Shows/hides the color format selector dropdown and associated input fields. When enabled, users can switch between HEX, RGB, HSL, and HSV formats and input color values directly.                                                                 | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showColorPalette`        | `show-color-palette`         | Shows/hides the color palette section. Displays a customizable grid of color swatches for quick selection. The `colorPalette` property must also have items for the palette to be visible.                                                         | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showColorPreview`        | `show-color-preview`         | Shows/hides the current color preview box. Displays the currently selected color with proper transparency pattern for alpha values.                                                                                                                | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `showHueSlider`           | `show-hue-slider`            | Shows/hides the hue slider control. Allows users to select the color hue (0-360 degrees).                                                                                                                                                          | `boolean`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `translations`            | --                           | Specifies the literals required in the control. Some translation strings support the `SELECTED_COLOR` token placeholder which is replaced at runtime with the actual color value (e.g., `colorPaletteButton` and `currentColorPreview`).           | `{ accessibleName: { lightnessChannelInput: string; hueChannelInput: string; saturationChannelInput: string; valueChannelInput: string; alphaChannelInput: string; redChannelInput: string; greenChannelInput: string; blueChannelInput: string; hexadecimalInput: string; colorFormatOptions: string; colorFieldDescription: string; colorFieldControl: string; hueSliderControl: string; alphaSliderControl: string; colorPaletteButton: string; currentColorPreview: string; }; text: { colorFieldLabel: string; alphaChannelLabel: string; hueChannelLabel: string; colorPaletteSection: string; colorFormatSelector: string; currentColorPreviewText: string; hexadecimalFormat: string; rgbColorFormat: string; hslColorFormat: string; hsvColorFormat: string; redChannelInputLabel: string; greenChannelInputLabel: string; blueChannelInputLabel: string; hueChannelInputLabel: string; saturationChannelInputLabel: string; lightnessChannelInputLabel: string; valueChannelInputLabel: string; }; }` | `{     accessibleName: {       lightnessChannelInput: "Lightness",       hueChannelInput: "Hue",       saturationChannelInput: "Saturation",       valueChannelInput: "Value",       alphaChannelInput: "Alpha",       redChannelInput: "Red",       greenChannelInput: "Green",       blueChannelInput: "Blue",       hexadecimalInput: "Hexadecimal color",       colorFormatOptions: "Color format options",       colorFieldControl: "Color field",       colorFieldDescription: "2d color field",       hueSliderControl: "Hue Slider",       alphaSliderControl: "Alpha Slider",       colorPaletteButton: `Selected color ${SELECTED_COLOR}`,       currentColorPreview: `Current color: ${SELECTED_COLOR}`     },     text: {       colorFieldLabel: "",       colorPaletteSection: "Color Palette",       colorFormatSelector: "Color Format",       currentColorPreviewText: "Color Preview",       hueChannelLabel: "Hue",       alphaChannelLabel: "Alpha",       hexadecimalFormat: "HEX",       rgbColorFormat: "RGB",       hslColorFormat: "HSL",       hsvColorFormat: "HSV",       redChannelInputLabel: "R",       greenChannelInputLabel: "G",       blueChannelInputLabel: "B",       hueChannelInputLabel: "H",       saturationChannelInputLabel: "S",       lightnessChannelInputLabel: "L",       valueChannelInputLabel: "V"     }   }` |
| `value`                   | `value`                      | The current value of the `ch-color-picker` component, representing a color in one of the following formats:   - HEX   - HSL   - HSV   - RGB This value determines the selected color and can be updated by the user.                               | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `FALLBACK_COLOR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Events

| Event   | Description                                                                                                                                                                                                | Type                                                                                               |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `input` | The `input` event is emitted whenever the color value changes. The event detail payload is a `ColorVariants` object which provides the color in all supported formats simultaneously (HEX, RGB, HSL, HSV). | `CustomEvent<{ rgb: string; rgba: string; hsl: string; hsla: string; hex: string; hsv: string; }>` |

## Dependencies

### Depends on

 - [ch-color-field](../ch-color-field/README.md)
 - [ch-slider](../ch-slider/README.md)
 - [ch-combo-box-render](../ch-combo-box-render/README.md)

### Graph
```mermaid
graph TD;
  ch-color-picker --> ch-color-field
  ch-color-picker --> ch-slider
  ch-color-picker --> ch-combo-box-render
  ch-combo-box-render --> ch-popover
  style ch-color-picker fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------


