GradientPicker

Gradient picker: a stop strip with draggable thumbs, an editable CSS value field, a fully accessible colour-stop list (each stop opens a ColorPicker in a popover), and per-type geometry controls (linear angle + dial, radial size/position, conic position).

The value contract is a CSS gradient string — linear-gradient(…), radial-gradient(…) or conic-gradient(…) — accepted (pasted or typed) and emitted. Stops keep whatever colour strings the ColorPicker accepts, including var(--x) references. An unparseable value falls back to a default gradient in the controls; committing any edit replaces it.

import { GradientPicker, GradientBar } from '@tangible/ui';

Interactive docs and examples: GradientPicker in Storybook.

GradientPicker props

Prop	Type	Default	Description
`alpha?`	`boolean`	`true`	Show alpha in the per-stop colour pickers.
`aria-label?`	`string`		Accessible name for the picker group. Takes precedence over `labels.group`. Defines a string value that labels the current element.
`className?`	`string`
`defaultValue?`	`string`	`a two-stop linear gradient`	Uncontrolled initial value.
`disabled?`	`boolean`
`formats?`	`ColorFormat[]`	`all`	Formats offered in the per-stop colour pickers.
`labels?`	`GradientPickerLabels`		Override any user-facing string for i18n.
`onValueChange?`	`(value: string) => void`
`value?`	`string`		Controlled value — a CSS gradient string.

Also accepts the standard attributes of HTMLAttributes (data-*, aria-*, event handlers), passed to the element it renders.

GradientBar props

The stop strip — stops rendered left-to-right as a linear gradient with a draggable thumb per stop, regardless of the gradient's actual type (the strip edits the stop list, not the geometry). Each thumb is a role="slider" for its position: arrows nudge (Shift = ×10), Home/End jump, Delete removes, Enter/Space opens the stop's colour editor. Clicking the track between thumbs adds a stop there. The stop LIST rendered by GradientPicker remains the fully accessible editing surface; the bar is the direct-manipulation view of the same data.

Prop	Type	Description
`stops`	`GradientStop[]`	Expected sorted by position — thumbs render (and tab) in array order.
`activeIndex?`	`number \| null`	Highlighted stop (the one being edited).
`aria-label?`	`string`
`className?`	`string`
`disabled?`	`boolean`
`labels?`	`GradientBarLabels`
`onActiveIndexChange?`	`(index: number) => void`
`onStopActivate?`	`(index: number) => void`	Enter/Space or click on a thumb — open this stop's colour editor.
`onStopAdd?`	`(position: number) => void`	Track click between thumbs. The owner inserts and seeds the colour.
`onStopPositionChange?`	`(index: number, position: number) => void`	Raw position from drag / keyboard — the owner clamps (e.g. to neighbours).
`onStopRemove?`	`(index: number) => void`	Delete/Backspace on a thumb. The owner enforces the two-stop minimum.

Other exports

defaultGradientPickerLabels: Required<GradientPickerLabels>

Examples

Conic: A parsed from angle survives the round-trip even though the panel has no control for it yet.
var() stop colors: Stop colours can be var(--x) references — kept verbatim in the emitted value, rendered by CSS wherever the variable resolves.
GradientBar (primitive): The stop strip is exported standalone (like ColorArea/ColorSlider) for custom compositions. The owner clamps positions and owns the stop data.
Pasted CSS normalises: The value field accepts hand-written CSS — to right, missing stop positions, double-position stops — and normalises it into the canonical emitted form.

Other stories: Full picker (linear), Radial, Many stops + alpha, Disabled (interactive page).

Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

--tui-gradient-bar-height
--tui-gradient-bar-radius
--tui-gradient-bar-thumb-size
--tui-angle-dial-size