# Input Color

A compact inline control for previewing and editing a colour value — a colour swatch alongside an editable hex or RGB field, with optional transparency (alpha). Use it on its own, or as the inline trigger that opens a `ColorPicker`. Works on web and React Native via `XUIProvider` themed contexts.

## Installation

```bash
npm install @xsolla/xui-input-color
```

## Imports

```tsx
import { InputColor } from '@xsolla/xui-input-color';
import type {
  InputColorProps,
  InputColorType,
  InputColorSize,
} from '@xsolla/xui-input-color';
```

## Quick start

```tsx
const [color, setColor] = useState('#22A8C3');

<InputColor value={color} onChange={setColor} />;
```

## API Reference

### `<InputColor>`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Controlled colour as a hex string (e.g. `#22A8C3`; `#RRGGBBAA` when `transparency` is on). |
| `defaultValue` | `string` | `'#000000'` | Initial value for uncontrolled usage. |
| `onChange` | `(value: string) => void` | — | Change handler; always receives a hex string (8-digit when `transparency` is on). |
| `onSwatchClick` | `() => void` | — | Fired when the swatch is activated. The swatch is interactive **only** when `type="color"` — use it to open a parent `ColorPicker`. Never called for other types. |
| `type` | `'color' \| 'color-hex' \| 'color-rgb' \| 'hex' \| 'rgb'` | `'color-hex'` | Which controls render (see [Types](#types)). |
| `transparency` | `boolean` | `false` | Add an alpha (`%`) field and a transparency-aware swatch. |
| `size` | `'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs'` | `'md'` | Control size. |
| `label` | `string` | — | Visible label shown above the control. |
| `id` | `string` | `auto` | HTML id used for accessibility linking. |
| `aria-label` | `string` | — | Accessible name when no visible label is present. |
| `testID` | `string` | — | Test identifier. |

Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).

The canonical value is always a hex string, regardless of `type`. The hex and RGB fields are alternate editable representations of the same colour; editing either emits an updated hex through `onChange`.

## Types

| `type` | Shows |
| --- | --- |
| `color` | Swatch only — acts as a trigger (`onSwatchClick`). |
| `color-hex` | Swatch + hex field. |
| `color-rgb` | Swatch + R / G / B fields. |
| `hex` | Hex field only. |
| `rgb` | R / G / B fields only. |

When `transparency` is on, an alpha (`%`) field is appended to every type and `color` gains it too.

## Examples

### Hex field (default)

```tsx
const [color, setColor] = useState('#22A8C3');

<InputColor value={color} onChange={setColor} />;
```

### RGB channels

```tsx
const [color, setColor] = useState('#22A8C3');

<InputColor type="color-rgb" value={color} onChange={setColor} />;
```

### Transparency (alpha)

```tsx
const [color, setColor] = useState('#22A8C380');

<InputColor type="color-rgb" transparency value={color} onChange={setColor} />;
```

### Sizes

```tsx
<InputColor size="xl" defaultValue="#22A8C3" />
<InputColor size="md" defaultValue="#22A8C3" />
<InputColor size="xs" defaultValue="#22A8C3" />
```

### Swatch as a ColorPicker trigger

`type="color"` renders the swatch alone; wire `onSwatchClick` to open a parent `ColorPicker`.

```tsx
const [color, setColor] = useState('#22A8C3');
const [open, setOpen] = useState(false);

<InputColor
  type="color"
  value={color}
  onChange={setColor}
  onSwatchClick={() => setOpen(true)}
/>;
```

### With a label

```tsx
const [color, setColor] = useState('#22A8C3');

<InputColor value={color} onChange={setColor} label="Brand color" />;
```

## Accessibility

- The control is a `role="group"`; label it with `label`, `aria-label`, or an external `aria-labelledby` target.
- Each editable field has an `aria-label` — `"Hex color value"`, `"Red channel"`, `"Green channel"`, `"Blue channel"`, `"Opacity percentage"`.
- For `type="color"` the swatch is a `<button aria-label="Open color picker">`; for every other type it is a decorative preview marked `aria-hidden` (not focusable, not clickable).
- Numeric fields (R / G / B, alpha) step by ±1 with the `ArrowUp` / `ArrowDown` keys, clamped to their range (0–255, or 0–100 for alpha).
- A visually hidden `role="status"` / `aria-live="polite"` region announces colour changes to screen readers (e.g. "Color updated to #FF0000").
- Editing updates the swatch live as you type; the value commits (and normalizes — shorthand expand, uppercase, clamp) on blur, `Enter`, or `Tab`.
- The transparency checkerboard behind a translucent colour is rendered with CSS and is web only; the solid swatch and alpha split render on native.