Color Swatch

Usage

import { ColorSwatch } from '@appica/ui-react/color-swatch'
import { parseColor } from '@appica/ui-react/color'

<ColorSwatch color="#3b82f6" />

ColorSwatch shows one color as a tile. It's the read-only member of the color family: Color Area and Color Slider pick a color, and the swatch reports the one you landed on. All three take the same Color value, so a swatch drops into a picker with no conversion.

const [color, setColor] = useState(() => parseColor('#3b82f6'))

<ColorSwatch color={color} />

color takes a Color or any CSS color string, so '#3b82f6', 'rgba(59, 130, 246, 0.7)' and a parsed object are all equivalent.

The swatch borrows the border and the disabled treatment from the other two controls, so a picker built out of the family reads as one control rather than three.

Inside a Color Picker, color is optional: a bare <ColorSwatch /> previews whatever the picker currently holds.

Examples

Opacity

A translucent color composited straight onto the page is indistinguishable from the lighter opaque color it resolves to. The swatch draws it over a checkerboard instead, the same backdrop a channel="alpha" slider uses, so the transparency is visible.

checkerboard={false} turns it off, which lets the swatch blend into whatever sits behind it instead. The row below is the default, the row under it the same colors without the backdrop.

import { ColorSwatch } from '@appica/ui-react/color-swatch'

const steps = [1, 0.75, 0.5, 0.25, 0.1]

export default function ColorSwatchOpacity() {
  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex items-center gap-4">
        {steps.map((alpha) => (
          <ColorSwatch key={alpha} color={`rgba(59, 130, 246, ${alpha})`} />
        ))}
      </div>
      <div className="flex items-center gap-4">
        {steps.map((alpha) => (
          <ColorSwatch key={alpha} color={`rgba(59, 130, 246, ${alpha})`} checkerboard={false} />
        ))}
      </div>
    </div>
  )
}

Shapes

shape="rounded" is the default. Its corner is a percentage of the swatch, so it stays proportional at every size instead of flattening out as the tile grows - the same trick Avatar and Thumbnail use. shape="circle" is the alternative, and pairs well with an inline mention of a color in running text.

import { ColorSwatch } from '@appica/ui-react/color-swatch'

export default function ColorSwatchShapes() {
  return (
    <div className="flex items-center gap-4">
      <ColorSwatch color="#3b82f6" />
      <ColorSwatch color="#3b82f6" shape="circle" />
    </div>
  )
}

Sizing

The swatch is 40px square by default. size runs 3xs 16px through xl 64px: the same ladder Avatar and Thumbnail use, shifted one step down because a swatch is read beside a value rather than looked at. Every shared name keeps its pixel size, so sm is 32px on all three. A plain pixel number works too, and a size-* class on the root overrides both.

import { ColorSwatch } from '@appica/ui-react/color-swatch'

const sizes = ['3xs', '2xs', 'xs', 'sm', 'md', 'lg', 'xl'] as const

export default function ColorSwatchSizes() {
  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex flex-wrap items-center justify-center gap-4">
        {sizes.map((size) => (
          <ColorSwatch key={size} color="#3b82f6" size={size} />
        ))}
      </div>
      <div className="flex items-center gap-4">
        <ColorSwatch color="#a855f7" size={56} />
        <ColorSwatch color="#a855f7" className="size-24" />
      </div>
    </div>
  )
}

Building a picker

An area for two channels, a hue slider for the third, an alpha slider, and a swatch for the result - the same four parts the Color Area and Color Slider pages build. The swatch is the only one of them that shows the alpha as alpha.

'use client'

import { useState } from 'react'
import { ColorArea } from '@appica/ui-react/color-area'
import { ColorSlider } from '@appica/ui-react/color-slider'
import { ColorSwatch } from '@appica/ui-react/color-swatch'
import { type Color, formatColor, parseColor } from '@appica/ui-react/color'

export default function ColorSwatchPicker() {
  const [color, setColor] = useState<Color>(() => parseColor('hsb(217, 76%, 96%)'))

  return (
    <div className="flex w-full max-w-56 flex-col gap-3">
      <ColorArea
        value={color}
        onValueChange={setColor}
        xChannel="saturation"
        yChannel="brightness"
        aria-label="Saturation and brightness"
      />
      <ColorSlider channel="hue" value={color} onValueChange={setColor} />
      <ColorSlider channel="alpha" value={color} onValueChange={setColor} />
      <div className="flex items-center gap-3">
        <ColorSwatch color={color} />
        <span className="font-mono text-xs text-nowrap">
          {color.alpha < 1 ? formatColor(color, 'rgba') : formatColor(color, 'hex')}
        </span>
      </div>
    </div>
  )
}

Disabled

disabled swaps the color for a flat muted fill inside a dashed outline, dimmed. It's the same treatment the area and the slider use, for a color a palette can't offer right now.

import { ColorSwatch } from '@appica/ui-react/color-swatch'

export default function ColorSwatchDisabled() {
  return (
    <div className="flex items-center gap-4">
      <ColorSwatch color="#3b82f6" disabled />
      <ColorSwatch color="#3b82f6" shape="circle" disabled />
    </div>
  )
}

API reference

Every other <span> attribute is forwarded to the root. The root carries data-disabled; the parts are addressable through data-slot (color-swatch, color-swatch-surface).

The color model - Color, parseColor, formatColor, convertColor and the channel helpers - ships from @appica/ui-react/color and is documented on the Color Area page.

Accessibility

• The swatch is a role="img" with a name, not a decorative div, so a color that carries meaning is reachable rather than invisible.
• That name is an English description built from the color - vivid blue, dark muted green, light gray - because a hex string is announced digit by digit and tells a listener nothing. Below full opacity it ends with the opacity, e.g. vivid blue, 50% opacity.
• colorName replaces that description with the name your palette uses. aria-label is appended to it rather than replacing it, so colorName="Fire truck red" with aria-label="Background color" announces Fire truck red, Background color.
• The hairline border is drawn as an overlay rather than as a border on the root, so it survives a pale color without changing the swatch's box.
• forced-color-adjust: none keeps the color and the checkerboard intact in forced-colors mode, where the whole point of the component would otherwise be overridden.
• A swatch is not a control. When it needs to be clickable, wrap it in a <button>: that gives you the focus ring, the pressed state and the keyboard handling for free, and keeps the swatch itself presentational.