swatchbook

A tiny (~2 kB, 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.

Install

npm

npm install swatchbook

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

CDN — no build step, no install:

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

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.

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