---
title: Swatch
description: A color or a pattern as a value, drawn as a circle or a square and named in words for the reader who cannot see it.
visibility: guest
draft: false
---

# 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](/components/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:

:::preview{title="A color and its name"}
<x-wirekit::swatch color="#1e3a8a" label="Navy" />
:::

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

:::preview{title="The name beside the swatch"}
<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:

:::preview{title="Finishes as pictures"}
<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:

:::preview{title="A value that is not available"}
<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:

:::preview{title="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](/components/swatch-group#keyboard-interaction).

## 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`:

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