Swatch

Low-level visual swatch primitive for colours, gradients, and images — shaped as a **chip** (circle/pill) or a **tile** (square material/image card). A thin façade dispatching on shape to the internal chip and tile renderers, which share fill resolution and contrast handling. Chips paint the darkening overlay on every fill and draw the double-ring selection pattern; tiles reproduce the retired Thumbnail exactly (tiered radius/border/ring/shadow, children > src > color precedence, no darkening overlay).

Usage

import { ChipSwatchProps, computeSwatchFanTransforms, getStackedSwatchFanFrame, getStackedSwatchFanTarget, StackedSwatchFan, StackedSwatchFanItem, StackedSwatchFanProps, Swatch, SwatchColorStop, SwatchFrameRing, SwatchProps, TileSwatchProps } from "@desk/ui/components/swatch";

Best practices

Feed fills through color/background/colors, never a hex in className/style — the props drive the contrast-aware text colour, selection ring, and darkening overlay.
Reach for Swatch for a selectable colour/gradient/material chip or tile; a tiny non-interactive status marker is Dot, and a display-only status/category label is Badge.
For a gradient or image chip fill pass light — auto contrast detection (isLightColor) only reads solid colours, so overlaid icons/labels lose legibility without it.

Props

StackedSwatchFan

Prop	Type	Default	Description
fanOnHover	`boolean`	`true`	When `true` (default), the stack owns its own fan state via hover/focus. Set `false` to drive it externally through the controlled `fanned` prop.
fanned	`boolean`		Controlled fan state — use when a sibling element (e.g. a CTA) triggers the fan.
items(required)	`StackedSwatchFanItem[]`		Swatch fills to stack; only the first few (matching the motion transforms) render.
label	`string`	`"Material swatches"`	Accessible label applied as the fan's `aria-label`.
onFannedChange	`(fanned: boolean) => void`		Fires when the fan opens or closes, with the next fanned state.

Swatch

Prop	Type	Default	Description
background	`string \| undefined`		CSS background value for the swatch fill. Accepts any valid CSS `background` — gradients, images, or solid colors. Takes precedence over `color` when both are provided. Use this for gradient or image fills. Background CSS value (gradient/image) — only the legacy `floating` variant paints it
children	`ReactNode`		Image or custom content rendered on top of the color Custom content — takes precedence over `src` and `color`
className	`string \| undefined`		Additional className Additional className for the outer container
color	`string \| undefined`		CSS color value (hex, rgb, hsl, etc.) — convenience prop for solid fills. Background color (solid fill, no image)
alt	`string \| undefined`		Alt text for the image (used when `src` is provided). Alt text for the image (used when `src` is provided)
light	`boolean \| undefined`		Override light color detection for contrast handling. Required when using `background` for a gradient — `isLightColor` only works for solid colors. Contrast override for overlaid content on the legacy `floating` variant — `isLightColor` only reads solid colours, so gradient/image fills need it.
ref	`((instance: HTMLDivElement \| null) => void \| (() => void \| { [UNDEFINED_VOID_ONLY]: never; }) \| import("react").DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof import("react").DO_NOT_`		Forwarded ref to the root span. Needed for m.create(Swatch). Forwarded ref to the root element.
selected	`boolean \| undefined`		Whether this swatch appears selected Selection state - shows primary border + elevated shadow (card variant only)
shape	`"tile" \| SwatchChipShape`	`"circle"`	Chip shape variant: "circle" (default) or "pill" (wide rounded rectangle). Pill shape is 144×48 with rounded-3xl corners — used by Color Studio for colour name pills and back-navigation targets. Tile geometry discriminant. Always "tile" — chip shapes live on the `ChipSwatchProps` union member.
size	`number \| "base" \| "2xs" \| "xs" \| "sm" \| "lg" \| "xl" \| "2xl" \| "3xs" \| "fluid" \| undefined`		Size from the chip swatch size system. Ignored when shape="pill". Size - SwatchTileSize scale ("xs", "base", "2xl"), pixel number, or "fluid"
src	`string \| undefined`		Image source URL — rendered as a native `<img>` fill (object-cover) on top of any color/gradient fill. Ignored when `children` is provided. Image source URL — renders a native `<img>` with `object-cover`
style	`import("react").CSSProperties \| undefined`		Inline styles (useful for pixel-based sizing) Inline styles (useful for motion animations)

SwatchFrameRing

Prop	Type	Default	Description
radius(required)	`string`

Also exports

interfaceChipSwatchProps
constcomputeSwatchFanTransforms
constgetStackedSwatchFanFrame
constgetStackedSwatchFanTarget
interfaceStackedSwatchFanItem
interfaceStackedSwatchFanProps
typeSwatchColorStop
typeSwatchProps
interfaceTileSwatchProps

Composition

Builds on

Icon

Used by

SwatchFan, SwatchGroup, SwatchSelector