Swatch
Inline color blocks for quick preset-color selection and display — for theme colors, tag colors, favorite colors and other "pick a color without opening a panel" scenarios. oas-swatch is the color block; oas-swatch-group is the selection group (single-select radio semantics / multi-select checkbox semantics, roving keyboard navigation).
Basic usage
Single-select group: click a swatch to select it (selected state = outer ring); oas-change carries the selected value.
Selected state
Single select
Multiple select
With multiple, the group uses checkbox semantics; value is a comma-separated list of selected values (prefer preset names or hex colors for the multiple-value channel — color values containing commas, such as rgb(1,2,3), conflict with the comma separator and are not recommended inside a multiple group).
Multiple select
Shapes and sizes
shape has three forms (square / rounded / circle); size has five steps (xs / small / medium / large / xl).
Shapes and sizes
Nothing and mixed
nothing marks a no-color/transparent swatch (checkerboard base); mixed marks a multi-color swatch (mosaic, for merged multi-value scenarios).
Nothing and mixed
Controlled selection (value)
The group value is a controlled channel: setting the attribute externally updates the selected state immediately.
Controlled value
Keyboard navigation
Tab enters the group (single roving stop) → arrow keys move focus (horizontal keys mirror in RTL) → Enter/Space selects → Home/End jump to first/last. Disabled swatches are skipped in the roving order.
API
oas-swatch
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
aria-label | Accessible name override (host-written value takes top priority) | — | — |
color | Fill color (any CSS color or one of 11 preset names, unified color protocol) | string | — |
disabled | Disable the swatch (not clickable, not focusable) | boolean | — |
label | Accessible name (defaults to i18n swatch.color + the color value) | — | — |
mixed | Mixed-color indicator (mosaic, for merged multi-value scenarios) | boolean | — |
nothing | No-color/transparent indicator (checkerboard base, color-independent) | boolean | — |
selected | Controlled selected state (outer ring; driven by oas-swatch-group inside a group) | boolean | — |
shape | Shape: square / rounded (default) / circle | string | rounded |
size | Side-length step: xs / small / medium (default) / large / xl | string | — |
Property (JS property; see each row for attribute reflection)
| Property | Description | Type | Default |
|---|---|---|---|
value | Current value: the swatch color identifier (i.e. the color attribute) | string | — |
Events
| Event | Description |
|---|---|
oas-click | Click, detail: { color } (intercepted by the group which emits the group-level oas-change) |
oas-swatch-group
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
aria-label | Group accessible name (locale fallback by default) | — | — |
disabled | Disable the whole group (propagated to children) | boolean | — |
multiple | Multiple-select mode (checkbox semantics) | boolean | — |
value | Current value: child swatch's color in single select; comma-separated list in multiple select | string | string[] | — |
Property (JS property; see each row for attribute reflection)
| Property | Description | Type | Default |
|---|---|---|---|
value | Current value: the selected color string, or an array of colors when multiple | string | string[] | — |
Events
| Event | Description |
|---|---|
oas-change | Selection change, detail: { value: string | string[] } |
Slots
| Name | Description |
|---|---|
| default | Swatch children (<oas-swatch>) |