Swatch

Color, gradient, image, and weighted palette swatches with selection, remove, unavailable, and contrast-aware states.

Finishes

Palettes

Gradients

Patina

Copper

Stone

Ember

Moss

Dune

States

Selected

Default

Raised

Unavailable

Distribution

79% assigned21% unassigned

Adjustable distribution

Evergreen 48%Saffron 30%Oxblood 22%

Install

npm install @patternmode/swatch

import {
  DistributionBar,
  DistributionDisplay,
  Swatch,
} from "@patternmode/swatch";
import "@patternmode/swatch/styles.css";
import { useState } from "react";

function PalettePreview() {
  const [segments, setSegments] = useState([
    { id: "evergreen", color: "#315c4b", label: "Evergreen", value: 48 },
    { id: "saffron", color: "#d9a441", label: "Saffron", value: 30 },
    { id: "oxblood", color: "#9b3d32", label: "Oxblood", value: 22 },
  ]);

  return (
    <>
      <Swatch
        aria-label="Palette"
        colors={[
          { color: "#315c4b", ratio: 60 },
          { color: "#e1ebe5", ratio: 40 },
        ]}
        shape="pill"
        size="2xl"
      />
      <DistributionBar
        aria-label="Finish distribution"
        onChange={setSegments}
        segments={segments}
      />
      <DistributionDisplay
        aria-label="Assigned finish distribution: 79% assigned, 21% unassigned"
        emptyValue={21}
        legend="summary"
        segments={[
          { id: "evergreen", color: "#315c4b", label: "Evergreen", value: 38 },
          { id: "saffron", color: "#d9a441", label: "Saffron", value: 24 },
          { id: "oxblood", color: "#9b3d32", label: "Oxblood", value: 17 },
        ]}
      />
    </>
  );
}

Core API

`Swatch`

Visual swatch primitive for solid colors, gradients, images, and weighted palettes.

color: stringCSS color value used for a solid swatch fill.
background: stringCSS background shorthand. Takes precedence over color and colors.
colors: Array<string | { color: string; ratio?: number }>Renders multiple color stops as one weighted palette fill.
children: ReactNodeOptional media rendered inside the swatch frame. Next.js consumers can pass next/image Image here.
shape: "circle" | "pill" | "square" | "block""circle"Controls the rendered silhouette.
flat: booleanfalseRemoves decorative shadow and scrim so the fill reads as an exact visual value.
texture: "atmosphere"Renders supplied colors as a qualitative atmosphere texture instead of a weighted palette.
density: number0.5Controls how tight or diffuse atmosphere texture pools appear.
gravity: number0Shifts atmosphere texture pools vertically without changing the visual value.
size: "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "6xl" | "7xl""base"Sets the swatch dimensions.
selected: booleanfalseShows selected state and optional icon overlay.
onRemove: () => voidAdds a hover/focus remove affordance.
removeLabel: stringAccessible label for the remove affordance. Defaults to the swatch label.

`DistributionBar`

Sibling primitive for editing weighted visual distributions with draggable boundary handles.

segments: Array<{ id: string; color: string; label?: string; value: number }>Segment weights and colors. Values render proportionally, and the legend shows derived percentages.
onChange: (segments) => voidCalled with the next segment values after drag or keyboard adjustment.
minValue: number4Smallest value each adjacent segment can be dragged down to.
step: number1Keyboard adjustment amount for ArrowLeft and ArrowRight.
legend: "segments" | false"segments"Shows or hides the per-segment derived percentage legend.
moveDistributionBoundary: (segments, boundaryIndex, deltaValue, minValue) => segmentsHelper for external controls that need to move a boundary without dragging.
updateDistributionSegment: (segments, id, update) => segmentsUpdates segment metadata such as id, color, or label while preserving its current value.
removeDistributionSegment: (segments, id) => segmentsRemoves a segment and redistributes its value across the remaining segments.

`DistributionDisplay`

Non-editing distribution primitive for read-only or selectable weighted visual displays.

segments: Array<{ id: string; color: string; label?: string; value: number }>Segment weights and colors. Values render proportionally without drag handles.
emptyValue: number0Optional unassigned weight rendered as a hatched remainder segment.
legend: "segments" | "summary" | false"segments"Controls whether the legend lists each segment, summarizes assigned/unassigned weight, or is hidden.
onSegmentSelect: (segment) => voidRenders segments as buttons and reports which segment the parent selected.
selectedSegmentId: stringMarks the selected segment when DistributionDisplay is used for selection.