swatchbook

A tiny (~2.5 kB min+gzip, zero-dependency) <swatch-book> web component that presents design variants one at a time as a carousel, instead of stacking them down the page. Drop in one script, wrap your candidate designs, and flip between them with arrows, dots, or the keyboard.

It's built for reviewing block/section design options — put two or three candidate heroes (or pricing tables, or CTAs) side-by-side-in-time and click through them. Because it's a plain custom element, it works in any stack: Astro, React, Vue, Svelte, or hand-written HTML.

<swatch-book label="Hero">
  <section data-swatch="Bold">…candidate A…</section>
  <section data-swatch="Minimal" data-default>…candidate B…</section>
  <section data-swatch="Playful">…candidate C…</section>
</swatch-book>

<script type="module" src="https://unpkg.com/swatchbook"></script>

The whole idea in one line: the script's presence is the switch. Include it and you get a carousel to review options; omit it (e.g. in production) and the book collapses to your chosen default — no trace of the tool.

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 (see Gotchas):

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:

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

Install

Script — no build step, no install, nothing left in package.json:

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

This is the recommended way in, because swatchbook is scaffolding: you add it to choose a design and delete it once you have. A <script> tag is one line to add and one line to remove — which is what the script's presence is the switch amounts to in practice. Drop the two tags into whichever page or layout renders the section you're reviewing.

pnpm — if you'd rather bundle it, or a CSP blocks third-party scripts:

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

| File | What it does | When you need it | | --- | --- | --- | | swatchbook.js | Defines <swatch-book> and turns it into a carousel. | Whenever you want the review UI. Its presence is the on/off switch. | | swatchbook.css | A :not(:defined) fallback that shows only the default swatch when the script is absent. | On any page that ships <swatch-book> markup but might load without the script (production, or pre-hydration). Recommended. |

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 the 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 + 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

| Attribute | Description | | --- | --- | | label | Optional heading shown in the control and used as the localStorage key for remembering the active swatch. |

Swatch attributes (on each direct child)

| Attribute | Description | | --- | --- | | data-swatch="Name" | Marks the element as a swatch; the value is its display name. Required on each swatch. | | data-default | Marks the swatch shown first (and the one the fallback CSS keeps). Falls back to the first swatch if omitted. |

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/focus 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. No polyfills shipped.

License

MIT © omaro