swatchbook

Demo

Three hero candidates in one book. Use the arrows, the dots, or the ← / → keys while focus is inside it. Your pick is remembered across reloads.

Use it with a coding agent

Generating the candidates is the slow part, so the shortest path is to let your agent write them and wire up the book in one go:

Give me three candidate designs for the pricing section, and wrap them in a
swatchbook so I can flip between them.

For something more deliberate, this template spells out the constraints that otherwise fail silently:

Use swatchbook to show me N candidate designs for [section]. Don't install it —
it's throwaway scaffolding. Load it from the CDN instead, by adding both tags to
whichever page or layout renders [section]:

  <script type="module" src="https://unpkg.com/swatchbook"></script>
  <link rel="stylesheet" href="https://unpkg.com/swatchbook/swatchbook.css" />

- Wrap the candidates in one <swatch-book label="[unique name]">.
- Each candidate is a DIRECT child with data-swatch="[Name]" — no wrapper
  element in between, or the book silently renders them stacked.
- Mark the one we'd ship with data-default.
- Keep the candidates' markup static; the component moves its own children.

Working in a repo where you'll do this often? Drop swatchbook's constraints into your agent's always-on context, so you don't have to restate them:

curl -fL https://unpkg.com/swatchbook/AGENTS.md >> AGENTS.md

Agents reading rather than writing: this page is available as markdown at /index.md and /llms.txt, or use the copy as markdown button up top.

Install

<script type="module" src="https://unpkg.com/swatchbook"></script>
<link rel="stylesheet" href="https://unpkg.com/swatchbook/swatchbook.css" />

pnpm add swatchbook

import "swatchbook";     // registers <swatch-book>
import "swatchbook/css"; // optional script-less fallback

Usage

Wrap your candidates in <swatch-book>. Each direct child with a data-swatch attribute is one swatch, and the attribute's value is its display name.

<swatch-book label="Pricing section">
  <div data-swatch="Cards">…</div>
  <div data-swatch="Table" data-default>…</div>
  <div data-swatch="Slider">…</div>
</swatch-book>

That's it. The component renders a small floating control — previous / next, dots, and a Label · Name · 2 / 3 readout — shows one swatch at a time, and remembers your last pick per label.

The two-file model

To ship a page without the tool, just don't include the script. With the CSS present, the page renders your data-default swatch as a normal, finished design.

Gotchas

When a book can't do its job it goes inert: it leaves your markup alone, so every candidate renders stacked down the page — the exact thing you installed this to avoid, looking for all the world like a CSS bug. Each case below logs a console.warn explaining itself, so check the console if a book does nothing.

Swatches must be direct children

This is the easy one to get wrong:

<!-- inert: the wrapper hides the swatches -->
<swatch-book label="Hero">
  <div class="grid gap-4">
    <section data-swatch="Bold">…</section>
    <section data-swatch="Minimal" data-default>…</section>
  </div>
</swatch-book>

A book needs at least two swatches

With zero or one there's nothing to flip between, so the component leaves your markup untouched.

Children must exist when the element upgrades

The book reads its swatches once, on connect. Swatches rendered in later — behind async data, say — are never picked up.

label must be unique per page

It doubles as the localStorage key, so two books sharing a label overwrite each other's remembered swatch.

Persistence overrides data-default

Once you've clicked through a book, the remembered swatch wins on reload. That's the point during a review, but it does mean data-default looks broken when you're testing it — clear the key first:

localStorage.removeItem("swatchbook:Hero");

Framework notes

<swatch-book> is a plain custom element, so it drops into any stack. Two things are worth knowing before you reach for one inside a component tree.

Keep a book's children static

Only the active swatch stays in the DOM — the component calls .remove() and .append() on its own light-DOM children (see how it works). Those children are exactly the nodes React, Vue, or Svelte believe they own. Static candidates are fine, since the framework never touches them after mount; but anything that re-renders a book's children will fight the component over the same nodes, and can throw when the framework tries to patch a swatch that's currently detached. Design candidates are usually static markup, so this rarely bites — but keep state, lists, and conditionals inside a swatch rather than around it.

TypeScript and JSX

The typings ship inside the package, so a script-tag setup has none, and <swatch-book> won't typecheck in .tsx. If you're writing JSX, add the package for its types and keep loading the runtime from the CDN:

pnpm add -D swatchbook   # types only — the script tag still does the work

That's enough for React 18 and below, Preact, Solid, and Qwik, which all read the global JSX namespace. Astro and Svelte accept hyphenated tags already and need nothing either way. React 19 moved its namespace to React.JSX and no longer reads the global one, so .tsx files there need a one-line opt-in:

// tsconfig.json
{ "compilerOptions": { "types": ["swatchbook/react"] } }

API

<swatch-book> attributes

Swatch attributes (on each direct child)

Interaction

• Arrows / dots in the floating control.
• ← / → when focus is anywhere inside the book.
• Wrap-around at both ends.
• Persistence — the active swatch is remembered per label via localStorage.

Events

The element fires a swatchchange event whenever the active swatch changes:

document.querySelector("swatch-book").addEventListener("swatchchange", (e) => {
  console.log(e.detail); // { index: 1, name: "Table" }
});

Styling the control

The control lives in a shadow root, so page CSS can't accidentally break it. To restyle it intentionally, target its part or tweak the fade:

swatch-book::part(chrome) {
  /* your own pill styling */
}

swatch-book {
  --sb-fade: 400ms; /* crossfade duration; 0 to disable */
}

How it works

• Swatches live in the light DOM, so your app's styles (Tailwind, global CSS, fonts) apply to them exactly as they would in the real page. Only the book's own control lives in a shadow root, so it neither leaks styles onto your page nor inherits them.
• Only the active swatch is mounted at any moment; the others are detached from the DOM. This is deliberate — components frequently ship global CSS with shared class names, and mounting several candidates at once would let their rules collide. Detaching also fully pauses each inactive swatch's animations and removes it from the tab order. The trade-off is that switching re-mounts a swatch, so its entry animations restart and the transition is a fade-in.

Browser support

Modern evergreen browsers (custom elements v1, shadow DOM, ::part, :has). No IE, and no polyfills shipped.