Swatch

<x-wirekit::swatch> shows a value that is a color or a pattern: the color of a product variant, a fabric, a finish. It draws a circle or a square filled with the color or the picture, and it carries the value's name, because a color says nothing to a reader who cannot see it.

To let the reader choose among swatches, use the swatch group: it puts each swatch in a native radio button or checkbox, which posts with a form and binds with wire:model.

Usage

Give the swatch a color and a label. The label is the swatch's name for assistive technology:

A color and its name

<x-wirekit::swatch color="#1e3a8a" label="Navy" />

Add show-label to show the name as text beside the swatch:

The name beside the swatch

Navy Chalk Coral

<x-wirekit::stack gap="sm">
    <x-wirekit::swatch color="#1e3a8a" label="Navy" show-label />
    <x-wirekit::swatch color="#f5f5f4" label="Chalk" show-label />
    <x-wirekit::swatch color="oklch(62% 0.19 30)" label="Coral" show-label />
</x-wirekit::stack>

A light color keeps its edge on a light page: every swatch has a border in the color the form fields use for theirs, which stands at 3:1 against the page.

A Pattern Instead of a Color

image fills the swatch with a picture, for a value no single color describes: a fabric, a wood grain, a leather. The picture is an <img> that covers the swatch, and the swatch's name names it:

Finishes as pictures

Linen Walnut

<x-wirekit::stack gap="sm">
    <x-wirekit::swatch image="/placeholder/96x96?bg=c2a878" label="Linen" show-label />
    <x-wirekit::swatch image="/placeholder/96x96?bg=7c4a2d" label="Walnut" show-label />
</x-wirekit::stack>

image takes an http or https address, or a path on your site. An address with any other scheme draws no picture.

The Colors It Accepts

color takes a hex color of three, four, six or eight digits (#fff, #1e3a8a, #1e3a8a80), rgb(), hsl() or oklch(). The color is written into the swatch's style attribute, so a value in any other form is rejected: WireKit reports it in development, and the swatch draws no fill instead of writing the value into your page. A color that comes from your database is checked the same way as one written in a template.

An Unavailable Value

unavailable draws a line across the swatch and adds "unavailable" to its name, so the state is in the picture and in the words:

A value that is not available

Navy

<x-wirekit::row gap="lg">
    <x-wirekit::swatch color="#1e3a8a" label="Navy" show-label />
    <x-wirekit::swatch color="#b91c1c" label="Red" show-label unavailable />
</x-wirekit::row>

Sizes and Shapes

size is sm (24px), md (32px, the default) or lg (40px). shape is circle, the default, or square, whose corners take the theme's small radius:

Three sizes, two shapes

<x-wirekit::row gap="md" align="center">
    <x-wirekit::swatch color="#0f766e" label="Teal, small" size="sm" />
    <x-wirekit::swatch color="#0f766e" label="Teal, medium" />
    <x-wirekit::swatch color="#0f766e" label="Teal, large" size="lg" />
    <x-wirekit::swatch color="#0f766e" label="Teal, square" shape="square" />
</x-wirekit::row>

The defaults come from config('wirekit.components.swatch').

Props

Prop	Type	Default	Description
`color`	`string\|null`	`null`	The value's color: a hex color, `rgb()`, `hsl()` or `oklch()`. Any other value is rejected and draws no fill
`image`	`string\|null`	`null`	A picture of the value in place of a color, as an `http` or `https` address or a path. It covers the swatch
`label`	`string\|null`	`null`	The value's name. It names the swatch for assistive technology, or stands beside it with `showLabel`. Without one the swatch is decorative and hidden from assistive technology
`showLabel`	`bool`	`false`	Show the name as text beside the swatch
`unavailable`	`bool`	`false`	Draw a line across the swatch and read "unavailable" with its name
`size`	`string`	`md`	`sm` (24px), `md` (32px) or `lg` (40px)
`shape`	`string`	`circle`	`circle` or `square`
`scope`	`string\|null`	`null`	Scoped personalization key

Accessibility

The name is always there. With label the swatch is an image named by it; with showLabel the name is text beside it, and the swatch itself is hidden from assistive technology so the name is read once. A swatch without a label is decorative: give it one unless the value's name already stands next to it.
No state rests on color alone. An unavailable value has a line across it and "unavailable" in its name.
A light color keeps its edge. The border is the form fields' resting border, at 3:1 against the page, so white on white stays visible.
The color survives a forced-colors theme. It is the content of the swatch, as a photo's colors are, so the fill opts out of the theme's color replacement, while the edge around it takes the theme's colors.

Keyboard Interaction

A swatch is not interactive and takes no focus. To choose among swatches with the keyboard, use the swatch group.

Design Tokens

Token	Use
`--size-wk-xs` / `--size-wk-sm` / `--size-wk-md`	The swatch at `sm`, `md` and `lg`
`--radius-wk-sm`	The corners of a square swatch
`--border-wk-width` + `--color-wk-border-strong`	The edge that keeps a light color visible on a light page
`--color-wk-text` + `--color-wk-surface`	The line across an unavailable value, and the halo that keeps it readable on a dark color
`--gap-wk-sm` + `--text-wk-sm`	The name beside the swatch

Customization

Set the default size and shape of every swatch in config/wirekit.php:

'components' => [
    'swatch' => ['size' => 'lg', 'shape' => 'square'],
],

Swatch

Was this page helpful?