Skip to content
Components

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 kind 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 use tiered radius, border, ring and shadow, children > src > color precedence, and no darkening overlay.

Usage

import { ChipSwatchProps, computeSwatchFanTransforms, getStackedSwatchFanFrame, getStackedSwatchFanTarget, StackedSwatchFan, StackedSwatchFanItem, StackedSwatchFanProps, Swatch, SwatchColorStop, SwatchFrameRing, SwatchProps, TileSwatchProps } from "@instruments/materia-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

PropTypeDefaultDescription
fanOnHoverbooleantrue

When true (default), the stack owns its own fan state via hover/focus. Set false to drive it externally through the controlled fanned prop.

fannedboolean

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.

labelstring"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

PropTypeDefaultDescription
backgroundstring | undefined

CSS background value for the swatch fill. Accepts any valid CSS background - gradients, images, or solid colours. 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

childrenReactNode

Image or custom content rendered on top of the colour Custom content - takes precedence over src and color

classNamestring | undefined

Additional className Additional className for the outer container

colorstring | undefined

CSS colour value (hex, rgb, hsl, etc.) - convenience prop for solid fills. Background colour (solid fill, no image)

altstring | undefined

Alt text for the image (used when src is provided). Alt text for the image (used when src is provided)

lightboolean | undefined

Override light colour detection for contrast handling. Required when using background for a gradient - isLightColor only works for solid colours. 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.

selectedboolean | undefined

Whether this swatch appears selected Selection state - shows primary border + elevated shadow (card variant only)

kind"tile" | SwatchChipForm"circle"

Chip kind: "circle" (default) or "pill" (wide rounded rectangle). Pill form is 144×48 with rounded-3xl corners - used for colour name pills and back-navigation targets. Tile geometry discriminant. Always "tile" - chip kinds live on the ChipSwatchProps union member.

sizenumber | "base" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xs" | "fluid" | undefined

Size from the chip swatch size system. Ignored when kind="pill". Size - SwatchTileSize scale ("xs", "base", "2xl"), pixel number, or "fluid"

srcstring | 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

styleimport("react").CSSProperties | undefined

Inline styles (useful for pixel-based sizing) Inline styles (useful for motion animations)

SwatchFrameRing

PropTypeDefaultDescription
radius(required)string

Also exports

  • interfaceChipSwatchProps
  • constcomputeSwatchFanTransforms
  • constgetStackedSwatchFanFrame
  • constgetStackedSwatchFanTarget
  • interfaceStackedSwatchFanItem
  • interfaceStackedSwatchFanProps
  • typeSwatchColorStop
  • typeSwatchProps
  • interfaceTileSwatchProps

Composition

Builds on

Center, Flex, Icon

Used by

SwatchFan, SwatchGroup, SwatchSelector, VariantSelector