Forms

ColorSwatchPicker

Keyboard-navigable listbox of preset color swatches that constrains selection to a curated palette.

import { ColorSwatchPicker } from '@lostgradient/cinder/color-swatch-picker';
formcolor
01

Overview

Presents a fixed palette of color swatches for constrained color selection.

Usage

svelte 
<script lang="ts">
  import ColorSwatchPicker from '@lostgradient/cinder/color-swatch-picker';

  const palette = [
    { color: '#ef4444', name: 'Red' },
    { color: '#f97316', name: 'Orange' },
    { color: '#eab308', name: 'Yellow' },
    { color: '#22c55e', name: 'Green' },
    { color: '#3b82f6', name: 'Blue' },
    { color: '#8b5cf6', name: 'Violet' },
  ];

  let selected = $state('#3b82f6');
</script>

<ColorSwatchPicker
  colors={palette}
  value={selected}
  label="Accent color"
  onValueChange={(color) => (selected = color)}
/>
<p style="margin-top: 0.5rem; color: var(--cinder-text-muted);">Selected: {selected}</p>
Live preview
02

When to use

Use when
  • Restricting color choice to a fixed brand or theme palette.
  • Pairing with color-picker as a shortcut for common values.
Avoid when
  • Letting users author arbitrary colors across the spectrum — use color-picker instead.
03

Examples

Basic color swatch picker

Keyboard-navigable preset palette constrained to brand colors.

04

Props

Props for color-swatch-picker
NameTypeDefaultDescription
value bindable text '' Bindable selected color.
colors required ColorSwatch[] Palette to render.
shape 'circle' | 'square' 'circle' Visual shape of each swatch. Default 'circle'.
size 'xs''sm''md''lg''xl' 'md' Swatch dimension token. Default 'md'.
layout 'grid' | 'stack' 'grid' Layout direction. Default 'grid'. Note: grid layout uses one-dimensional DOM-order navigation for both ArrowLeft/Right and ArrowUp/Down. True column-aware navigation is not implemented in v1 — see a11y memo.
disabled boolean false Disables the entire listbox. Keyboard activation and clicks are ignored.
label required text Accessible name for the listbox. Required — role="listbox" needs a label so screen readers can announce the control's purpose.
onValueChange (color: string) => void Fired when the selected swatch changes.
indicator snippet Snippet that replaces the default check-icon indicator on the selected swatch. Receives the active swatch and the computed contrast color for the icon.