{"slug":"color-picker","name":"ColorPicker","packageName":"@liquidify/react","category":"controls","maturity":"stable","summary":"A single control for choosing one colour — the canonical glass colour well.","importPath":"@liquidify/react/color-picker","sourcePath":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx","specPath":"packages/@liquidify/react/src/components/color-picker/spec.md","docsPath":"../liquidify-page/content/component-source/color-picker.md","documentationStatus":"stable","storyIds":["controls-color-picker--default"],"additionalExports":["ControlProps"],"anatomy":[{"name":"Label slot (leading)","description":"Label slot (leading) — the visible label text (from label), rendered"},{"name":"Well (decoration + host, trailing)","description":"Well (decoration + host, trailing) — a (.lq-color-picker-well)"},{"name":"Control","description":"Control — a native (.lq-color-picker-input)"}],"props":[{"name":"className","type":"string | undefined","required":false,"description":"Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"defaultValue","type":"string | undefined","required":false,"description":"Uncontrolled seed for the internal colour (ignored once {@link ColorPickerProps.value} is supplied).","defaultValue":"`\"#000000\"`","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"disabled","type":"boolean | undefined","required":false,"description":"When `true`, the whole control is dimmed, natively disabled, and removed from the tab order; no interaction commits a colour.","defaultValue":"`false`","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"label","type":"ReactNode","required":false,"description":"Visible label content — a string/number routes through the shared `Text` primitive (`color=\"inherit\"`, ADR-0028); an element (e.g. `Label(systemImage:)`) passes through unwrapped. Required for an accessible name unless an explicit `aria-label`/`aria-labelledby` is supplied via the inherited props.","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"labelProps","type":"LabelProps | undefined","required":false,"description":"Per-instance typography override for a string/number {@link label}, forwarded to the internal `Text` (ADR-0028).","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"labelsHidden","type":"boolean | undefined","required":false,"description":"Removes the visible label text while the accessible name persists (a visually-hidden label / `aria-label`).","defaultValue":"`false`","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"onChange","type":"((next: string) => void) | undefined","required":false,"description":"Fires with the next hex string on every colour change inside the OS picker — live, on each drag step. A same-value change emits nothing.","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"ref","type":"Ref<HTMLDivElement> | undefined","required":false,"description":"Forwarded ref to the rendered element — the outer wrapper `<div>` (charter §4 truthful ref; the documented semantic root, audit §8).","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"supportsOpacity","type":"boolean | undefined","required":false,"description":"Gates the alpha channel: sets the native control's `alpha` attribute, so the platform picker offers an opacity axis and the committed value carries `#RRGGBBAA`. On an engine that does not yet implement `alpha`, the attribute is ignored and the value degrades to `#RRGGBB` — a platform limitation, not a library behaviour.","defaultValue":"`true`","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"},{"name":"value","type":"string | undefined","required":false,"description":"Controlled current colour. Passing this switches ColorPicker to controlled mode: the rendered disc always reflects this value and the consumer owns it via {@link ColorPickerProps.onChange}. Serialised as `#RRGGBB`, or `#RRGGBBAA` when {@link ColorPickerProps.supportsOpacity}. Shorthand (`#RGB` / `#RGBA`) is accepted and expanded; an unparseable string falls back to opaque black.","declaredIn":"packages/@liquidify/react/src/components/color-picker/color-picker.tsx"}],"swiftUIMap":[{"swiftUI":"`ColorPicker(_ titleKey: LocalizedStringKey, selection:, supportsOpacity: Bool = true)`","react":"`label?: ReactNode` + `value?` / `defaultValue?` + `onChange` + `supportsOpacity?`","notes":"`titleKey` → the visible leading label **and** accessible name; a string/number `label` routes through the `Text` primitive (`color=\"inherit\"`, ADR-0028).","relationship":"direct"},{"swiftUI":"`ColorPicker(selection:, supportsOpacity:, label: () -> some View)`","react":"`label?: ReactNode` (custom content)","notes":"The custom-label overload; an element `label` (e.g. `Label(systemImage:)` → leading glyph + text) passes through unwrapped (ADR-0028).","relationship":"direct"},{"swiftUI":"`selection: Binding<Color>`","react":"`value?: string` (controlled) / `defaultValue?: string` (uncontrolled seed) / `onChange(next: string)`","notes":"The value triad (ADR-0015); controlled iff `value !== undefined` (audit §8). Colour serialised as a hex string — `#RRGGBB`, or `#RRGGBBAA` when `supportsOpacity`. Fires live during a drag, matching the SwiftUI binding.","relationship":"direct"},{"swiftUI":"`Binding<CGColor>` overload","react":"(same `value` string)","notes":"Web has one colour representation — the `CGColor` overload collapses to the hex string (inference).","relationship":"renamed"},{"swiftUI":"`supportsOpacity: Bool = true`","react":"`supportsOpacity?: boolean` (default `true`)","notes":"Sets the native control's `alpha` attribute, gating both the platform picker's opacity axis and the alpha channel in the committed value. Default `true` confirmed by render (the opacity-omitted \"Stroke\" well offers opacity).","relationship":"direct"},{"swiftUI":"`.labelsHidden()`","react":"`labelsHidden?: boolean` (default `false`)","notes":"Well-only, no visible label text; the accessible name **still** required (Accessibility). A label-presentation axis, independent of `disabled`.","relationship":"direct"},{"swiftUI":"`.disabled(true)`","react":"`disabled?: boolean` (default `false`)","notes":"Native `disabled` on the control (genuine inertness + removal from tab order) plus the library-standard dimmed treatment — a deliberate fidelity gap vs iOS's no-dimming.","relationship":"direct"},{"swiftUI":"`.font(_:)` / `.foregroundStyle(_:)` on the label","react":"`labelProps?: Pick<TextProps, …>`","notes":"Per-instance typography override forwarded to the internal `Text` label; token-backed axes only (ADR-0028). String labels only.","relationship":"direct"},{"swiftUI":"picker presentation (no SwiftUI counterpart — UIKit owns it)","react":"—","notes":"No presentation triad: the platform owns the picker surface and reports neither its open state nor its dismissal (see Out of scope).","relationship":"direct"},{"swiftUI":"`.controlSize(_:)`","react":"—","notes":"No size axis (see Sizes).","relationship":"direct"},{"swiftUI":"`.tint(_:)`","react":"—","notes":"No tint axis; the rainbow rim is fixed system chrome, theme-invariant (see Out of scope).","relationship":"direct"}],"tokens":["--lq-color-label-primary","--lq-color-picker-pad","--lq-color-picker-rim","--lq-color-picker-rim-w","--lq-color-picker-value","--lq-color-picker-well-size","--lq-glass-","--lq-hit-target-touch","--lq-lens-x","--lq-radius-pill","--lq-space-"],"keyboard":[{"key":"Keyboard","action":"Keyboard: Tab focuses the control; Enter / Space open the platform picker (native activation). Dismissal and in-picker keyboard handling belong to the OS. No component key handler exists."}],"variants":[],"variantPages":[]}