HySwatch

Usage examples on this page are written for Lit / plain HTML (<hy-swatch>). The same component ships as HySwatch in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A single selectable cell inside an hy-swatch-group.

hy-swatch is content-agnostic — it renders a sample (a color fill via the color attribute, or arbitrary default-slot content such as a gradient, image, or a dimension preview) plus a label. It has no knowledge of color math, ramps, or tokens; the parent group owns selection state, ARIA roles, roving tabindex, and keyboard interaction. Selection is shown by the cell's ring (border + background tint), not by color alone.

Label placement

• caption (default) — label sits below the sample. Serves dimension/size rungs.
• inset — label sits centered on the fill, with an auto-contrast treatment (mix-blend) so it stays legible on any color. Serves color ramps.

Used on its own, a swatch is presentational. Selection behaviour only exists inside hy-swatch-group, and so does the interactive chrome: the pointer cursor and hover ring appear only on a cell the group has given a role (single / multiple mode). In selection-mode="none" and standalone the cell is display-only — no hover, no selection ring.

Intrinsic size

The sample has a size of its own (--hy-swatch-size, 2.5rem by default; the group sets it per size): a floor it never goes under, which is also its rendered size wherever nothing stretches it. Inside a numeric-columns group it stretches to fill the track. Without the floor a shrink-wrapped swatch — a centered flex item, inline-block, a table cell — collapsed to its borders.

Accessible naming

When a swatch carries only a color (no caption text), it MUST be given an accessible name — selection cannot rely on color alone (WCAG 1.4.1). Provide a label, a caption slot, or aria-label on the host (e.g. label="Brand 500" or aria-label="Sky blue, #4A90E2"). A dev-mode warning fires when a color-only swatch has no name.

Examples

Color cell (inset label)

<hy-swatch
  value="500"
  color="#4A90E2"
  label="500"
  label-placement="inset"
  aria-label="Brand 500"
></hy-swatch>

Non-color cell (dimension rung)

<hy-swatch value="spacing.spa3" label="12px">
  <div class="rung-preview"></div>
</hy-swatch>

API

Properties

Property	Attribute	Type	Default	Description
value	value	string	''	Identity reported to the group on selection. Required when selectable.
color	color	string	''	Convenience fill for the sample square. Any CSS color or var(--hy-…).
label	label	string	''	Label text (e.g. a stop number or px value).
labelPlacement	label-placement	'caption' | 'inset'	'caption'	Where the label sits: caption (below) or inset (on the fill).
selected	selected	boolean	false	Whether this cell is selected. Managed by the group; reflected for styling.
disabled	disabled	boolean	false	Disables the cell, removing it from selection and keyboard navigation.
tooltip	tooltip	string	''	Hover/focus tooltip text — e.g. the resolved value (#d4d4d4). When set, the cell is wrapped in an hy-tooltip so the value surfaces on hover without a permanent on-screen readout. Empty = no tooltip. The cell stays the swatch host, so a wrapping hy-swatch-group's grid/selection is unaffected.

Slots

Slot	Description
default	Custom sample content (gradient, image, dimension preview). Overrides the color fill.
caption	Rich caption content below the sample. Overrides the label attribute.

CSS Parts

Part	Description
base	The cell wrapper (carries hover / selected / focus chrome).
sample	The visual sample square.
label	The inset label rendered over the sample.
caption	The caption text element below the sample.

CSS Custom Properties

Property	Description
--hy-swatch-border-hover	Cell border on hover.
--hy-swatch-border-selected	Cell border when selected.
--hy-swatch-background-hover	Cell background on hover.
--hy-swatch-background-selected	Cell background when selected.
--hy-swatch-sample-border	Border framing the sample square.
--hy-swatch-caption-color	Caption text color.
--hy-swatch-radius	Cell and sample corner radius.
--hy-swatch-gap	Internal gap and padding.
--hy-swatch-size	Minimum sample size (default 2.5rem; the group sets it per size).