Color Swatch

Anatomy

One element. It renders a <div> with role="img", an accessible name built from the value, and the colour as inline background — inline because there is no token for “the colour this client asked for”, and there should not be.

import { ColorSwatch } from '@comitor/ui'

<ColorSwatch
  color="#1F6FEB"            // a STORED value: hex, a named colour, or a colour function with plain arguments
  size="default"             // sm 24px · default 32px · lg 48px
  withoutTransparency        // optional: no checkerboard under a colour with alpha
/>
// → <div role="img" aria-label="Color swatch: #1F6FEB" data-slot="color-swatch" style="background-color: #1F6FEB" />

Sizes

sm fits a table row, default a form or a detail list, lg a header next to the colour’s details. All three keep the same border, so a white swatch still shows on a white page.

Transparency

A colour with alpha — 4- or 8-digit hex, rgba()/hsla(), any function with a / alpha, or transparent — is laid over a grey-and-white checkerboard, the convention every image editor uses for “see-through”. The checkerboard is the same in light and dark on purpose: a board that followed the theme would make the same 50% colour look different in each, so the swatch would misreport the very data it shows. withoutTransparency turns it off.

No colour yet

Leave color out, or pass an empty or blank string, and the square shows a thin diagonal stroke in the destructive-ink role, named “No color selected”. Map a null from your data to undefined — the prop is a string.

What counts as a colour

The value is data someone typed, and it ends up in a style attribute — so the swatch accepts only a closed grammar and nothing else reaches the page: hex with 3, 4, 6 or 8 digits; a single word of letters (red, rebeccapurple, transparent); or one colour function — rgb, hsl, hwb, lab, lch, oklab, oklch, color and the a variants — whose arguments are only letters, numbers, spaces and % . , / + -. That includes relative colours such as rgb(from red r g b). Everything else draws a transparent square: var(), color-mix(), a function inside a function, and anything with a ;, a colon or a quote that could break out of the declaration.

The rejection of var(--primary) is the point, not a gap: a token is interface colour, and the swatch is not the place for it. The grammar decides what is safe, not what is valid — notacolor is a word of letters, passes, and the browser simply drops the declaration. Validate when the value is saved, and store hex: it is what Color Picker posts from a form.

In a table

The shape the component was ported for: a list of records, each with a stored colour. Print the value next to the swatch — two near-identical blues are one colour to the eye and two to the person matching a brief — and say so in words when nothing is stored.

The white row is why the border exists: it uses the input role, the one that marks a boundary, not the decorative border. The semi-transparent row shows the checkerboard. With the hex printed beside it, a screen reader hears the value twice — once in the swatch’s name, once in the text. That is harmless; if a column repeats it hundreds of times, pass aria-hidden to the swatch and let the text carry it.

The accessible name

Every swatch is an image with a name: “Color swatch: ” followed by the value exactly as stored. A screen reader spells out a hex code, which is accurate but not friendly — when you know more than the value does (a colour name from the brief, what the colour is for), pass your own aria-label. It replaces the default whole.

asChild and children

With asChild the swatch renders no element of its own: its role, name, classes and background land on the single element you pass — here a <span>, so the swatch can sit inside a sentence where a <div> is not allowed. It needs exactly one child element; with none, nothing renders. Without asChild, children are drawn inside the square — a mark on top of the colour.

The child takes role="img", so do not merge a swatch onto a button or a link — it would stop being one for assistive technology. And a mark drawn on a colour the user chose has no guaranteed contrast — whatever colour you pick for it will vanish on some stored value, and no token can promise otherwise. Keep such marks decorative (aria-hidden) and say the same thing in text next to the swatch.

Language

Two strings, both heard and not seen. swatchLabel is a function of the value — “Color swatch: #1F6FEB”, “Mẫu màu: #1F6FEB” — and noColor names the empty square: “No color selected”, “Chưa chọn màu”. The per-instance override is aria-label, which beats the nearest ComitorLocaleProvider, which beats English.

An app that builds a whole message table of its own (a third language, typed as ComitorMessages) must add the colorSwatch namespace since 3.15.0, or typecheck fails. Where the provider goes: Get started → Set the language.

Props

Known limitations

• A rejected value is still named. The name is built from the string you passed, not from what was drawn: var(--primary) shows a transparent square announced as “Color swatch: var(--primary)”, and notacolor likewise. Validate before you store, and the two never disagree.
• No tokens, no mixing. var() and color-mix() are refused by design (see above). To show one of the package’s own colours, use the component that owns it — a Badge tone, a Status Pill.
• The package’s contrast gate does not see it. lint:a11y skips the inline style of an element whose class name has no literal string, which is how the swatch draws — so the data colour passes the gate without an exemption rather than with a measured one. The 3.15.0 release notes record this as a known, unpatched gap. It is one more reason the swatch must never carry interface meaning.
• Display only. The swatch is not focusable and has no click behaviour. To let someone enter or change a colour, use Color Picker.

Accessibility

• role="img" with an aria-label that includes the value, or “No color selected”. Pass aria-label to replace it.
• Children of an image are presentational: anything drawn inside the swatch is not read. Put meaning in the name or in text beside it.
• Colour must not be the only carrier (WCAG 1.4.1): print the value, or a name for it, next to the swatch, as the table demo does.
• The border uses the input role — 3.83:1 on the light background, 4.94:1 on dark — above the 3:1 WCAG 1.4.11 asks of a boundary that carries information.
• disabled sets aria-disabled and fades the swatch to 50%; it was never focusable, so nothing changes for the keyboard.
• forced-color-adjust: none keeps the stored colour visible in forced-colour modes.
• Never merge it onto a button or a link with asChild — role="img" replaces their role.

Related

• Color Picker — entering the colour this component later shows.
• Table — the rows a swatch most often sits in.
• Key Value — a detail page’s label-and-value list, where a swatch can sit beside the hex.