Color Picker

Pick a colour with a saturation / brightness area, hue and alpha sliders, a validated input and preset swatches. SColorPanel is the inline panel; SColorPicker opens it from a trigger in a popover, or in a bottom sheet on compact touch screens.

Usage

@Local color: string = '#3b82f6';

SColorPanel({ value: this.color!! })

Approximate web preview — the HarmonyOS rendering is the reference.

Picker in a form

The trigger is an outline button with the colour chip and value; triggerWidth: '100%' fills the field.

SFieldGroup() {
  SField() {
    SFieldLabel({ text: 'Project name' })
    SInput({ placeholder: 'Acme' })
  }
  SField() {
    SFieldLabel({ text: 'Brand color' })
    SColorPicker({ value: this.brand!!, triggerWidth: '100%' })
    SFieldDescription({ text: 'Used for buttons, links and highlights.' })
  }
}

Approximate web preview — the HarmonyOS rendering is the reference.

Alpha & formats

alpha adds an opacity slider; format sets the value format (hex, rgb, hsl, oklch) and formatToggle lets the input show any of them.

// alpha slider over a checkerboard; HEX / RGB / HSL / OKLCH toggle for the input
SColorPanel({ value: this.tint!!, alpha: true, format: 'rgb', formatToggle: true })

// value format of a picker: 'hex' (default) | 'rgb' | 'hsl' | 'oklch'
SColorPicker({ defaultValue: '#8b5cf6', format: 'hsl' })
SColorPicker({ defaultValue: '#8b5cf680', format: 'oklch', alpha: true })

Approximate web preview — the HarmonyOS rendering is the reference.

Swatches

swatches replaces the default palette ([] hides it); recent lists recently committed colours.

// custom presets + recently committed colours (shared by all pickers)
SColorPanel({
  value: this.accent!!,
  swatches: ['#0f172a', '#334155', '#64748b', '#e2e8f0', '#ef4444', '#f59e0b', '#22c55e', '#3b82f6'],
  recent: true
})

// compact: chip-only trigger, no input
SColorPicker({ value: this.accent!!, iconOnly: true, showInput: false, sizing: 'sm' })

Approximate web preview — the HarmonyOS rendering is the reference.

Controlled

onValueChange fires live while dragging; onValueCommit once on release and when the popover closes.

@Local value: string = '#f43f5e';
@Local changes: number = 0;
@Local committed: string = '#f43f5e';

SColorPicker({
  value: this.value!!,
  onValueChange: () => this.changes++,          // live while dragging
  onValueCommit: (v: string) => this.committed = v  // on release / close
})
SButton({ text: 'Reset', variant: 'outline', sizing: 'sm' }).onClick(() => this.value = '#f43f5e')

Approximate web preview — the HarmonyOS rendering is the reference.

API

Extracted from the @Param / @Event / @BuilderParam declarations in the library sources.

SColorPanel

Inline colour panel: a saturation / brightness area, a hue slider, an optional alpha slider (over a checkerboard), a preview swatch, a colour input, optional format toggle, preset swatches and recent colours. The body of {@link SColorPicker}'s popover; usable on its own.

• value / $value / defaultValue: a colour string in the format of the panel ('hex' default → #rrggbb, #rrggbbaa with alpha when translucent; 'rgb' | 'hsl' | 'oklch' → CSS functions). Any CSS colour SparkColor understands is accepted as input. Hex is CSS order: use SparkColor.parse(v).value (or sparkColorValueToArgb) for an ArkUI #AARRGGBB colour.
• onValueChange fires live while dragging; onValueCommit once per interaction (release, tap, key, swatch, Enter / blur of the input).
• The input accepts #RGB / #RRGGBB / #RRGGBBAA (and the other CSS forms); invalid text shows the error look and is reverted on blur. formatToggle adds a HEX / RGB / HSL / OKLCH button that only changes what the input displays.
• swatches (default: a shadcn-like palette; [] hides them), recent (recently committed colours, shared app-wide, see SparkColorRecents).
• Keyboard: arrows move the area thumb (saturation ←→, brightness ↑↓) and step the hue / alpha sliders.
• The trailing closure renders below the panel (e.g. actions).

Prop	Type	Default	Description
value!!	string | undefined	undefined	Controlled value (use with !!). Leave undefined for uncontrolled.
defaultValue	string	'#000000'	Uncontrolled initial value.
format	ColorPickerFormat ColorPickerFormat = 'hex' | 'rgb' | 'hsl' | 'oklch'	'hex'	Format of emitted values.
alpha	boolean	false	Show the alpha slider and keep alpha in values.
disabled	boolean	false
sizing	InputSize InputSize = 'sm' | 'default' | 'lg'	'default'	Size of the colour input / format button.
showInput	boolean	true	Show the colour input row.
formatToggle	boolean	false	HEX / RGB / HSL / OKLCH button that cycles the input's display format.
swatches	string[]	SPARK_DEFAULT_SWATCHES	Preset swatches (any CSS colours); [] hides the row.
recent	boolean	false	Show recently committed colours (shared by all panels).
panelWidth	Length | undefined	undefined	Panel width; undefined → --color-picker-width / 240vp. Pass '100%' to fill.
label	string | undefined	undefined	Accessible name prefix of the panel's controls.
tokens	ColorPickerTokens	{}	Per-instance token overrides (instance → theme --color-picker-* → recipe), see {@link ColorPickerTokens}.

Event	Type	Default	Description
onValueChange	(v: string) => void	() => { }	Live, while dragging.
onValueCommit	(v: string) => void	() => { }	Once an interaction ends (release, tap, key, swatch, input Enter / blur).

Slots: children (trailing closure)

SColorPicker

Colour picker: an outline-button trigger showing the colour chip and value (or only the chip with iconOnly) that opens an {@link SColorPanel} in a popover anchored below the trigger, or in a bottom sheet on compact touch windows (adaptive: 'auto').

Values follow {@link SColorPanel}: a colour string in format ('hex' default), onValueChange live while dragging, onValueCommit when an interaction ends and once more on close if the last value was not committed yet. The trailing closure renders at the bottom of the panel. tokens restyle the panel (--color-picker-*); surfaceTokens the popover surface (--popover-*).

Prop	Type	Default	Description
value!!	string | undefined	undefined	Controlled value (use with !!). Leave undefined for uncontrolled.
defaultValue	string	'#000000'
format	ColorPickerFormat ColorPickerFormat = 'hex' | 'rgb' | 'hsl' | 'oklch'	'hex'	Format of emitted values and of the trigger text.
alpha	boolean	false
disabled	boolean	false
sizing	InputSize InputSize = 'sm' | 'default' | 'lg'	'default'	Trigger (and panel input) size.
iconOnly	boolean	false	Square trigger showing only the colour chip.
triggerWidth	Length | undefined	undefined	Trigger width; undefined → fits its content.
formatToggle	boolean	false
showInput	boolean	true
swatches	string[]	SPARK_DEFAULT_SWATCHES
recent	boolean	false
label	string | undefined	undefined	Accessible name of the trigger (default "Pick a color").
adaptive	SparkAdaptive SparkAdaptive = 'auto' | 'pointer' | 'touch'	'auto'
tokens	ColorPickerTokens	{}	Panel tokens (instance → --color-picker-* → recipe).
surfaceTokens	SparkSurfaceTokens	{}	Popover surface tokens (instance → --popover-* → recipe).

Event	Type	Default	Description
onValueChange	(v: string) => void	() => { }
onValueCommit	(v: string) => void	() => { }
onOpenChange	(open: boolean) => void	() => { }

Slots: children (trailing closure)