split-flap-elements

Dependency-free, accessible split-flap displays built with Web Components. Use individual letters, numbers, words, symbols, or emoji; coordinate how cells settle; and restyle every surface with CSS custom properties and parts.

Open the live demo · Try every preset and build a board

The primary import registers <sfe-board> and <sfe-cell>. The package has zero runtime dependencies and uses a system font stack.

Editor and catalog tooling can discover both elements through the packaged Custom Elements Manifest.

Install

The npm release is forthcoming. After publication:

npm install split-flap-elements

To run the current source locally, use a web server—the demo will not work by opening its HTML with file://:

git clone https://github.com/gabeosx/split-flap-elements.git
cd split-flap-elements
npm ci
npm run dev

Quick start

With a bundler:

<sfe-board id="board" loop announce>
  <sfe-cell name="letter-0" preset="alpha"></sfe-cell>
  <sfe-cell name="letter-1" preset="alpha"></sfe-cell>
  <sfe-cell name="letter-2" preset="alpha"></sfe-cell>
</sfe-board>

<script type="module">
  import "split-flap-elements";

  const board = document.querySelector("#board");
  board.sequence = [
    { values: { "letter-0": "N", "letter-1": "Y", "letter-2": "C" } },
    { values: { "letter-0": "L", "letter-1": "A", "letter-2": "X" } },
  ];
  board.play();
</script>

Each uninitialized cell chooses a random position from its reel. Set value before connection when you need a deterministic start, including the alpha preset's blank value:

<sfe-cell name="letter" preset="alpha" value=" "></sfe-cell>

After npm publication, a no-build browser import can use an ESM CDN:

<script type="module">
  import "https://esm.sh/split-flap-elements";
</script>

Pin an exact package version in production. The primary entry point is browser-only because registration requires HTMLElement and customElements; client-only or deferred import is required in SSR applications. split-flap-elements/presets is DOM-free.

The live builder's Import style control generates either the bare npm specifier for bundlers or a version-pinned ESM CDN URL for direct browser use.

Reels and cells

Built-in presets all include a blank space:

| Preset | Reel | | -------------- | -------------------------- | | alpha | space, A–Z | | numeric | space, 0–9 | | alphanumeric | space, A–Z, 0–9 | | symbols | space, punctuation, arrows |

Use the reel property for arbitrary plain-text tokens:

const cell = document.querySelector("sfe-cell");
cell.reel = ["ON TIME", "BOARDING", "LAST CALL", "✓"];
await cell.spinTo("BOARDING");

HTML-authored reels use a non-empty JSON array of strings:

<sfe-cell reel='["SUNNY","RAIN","☂"]' value="SUNNY" span="4"></sfe-cell>

Targets absent from a cell's reel are rejected with sfe-config-error and do not corrupt playback state.

Cell API

| HTML attribute | Property | Default | Purpose | | -------------------- | ------------------- | ---------------- | ------------------------------------- | | name | name | "" | Key used in frame values | | preset | preset | alpha | Built-in reel | | reel | reel | alpha reel | JSON attribute or string[] property | | value | value | random reel item | Current/initial value | | span | span | 1 | Relative cell width/grid-column span | | flip-duration | flipDuration | 140 ms | Preferred per-flap cadence | | spin-duration | spinDuration | 1400 ms | Minimum spin window | | intermediate-order | intermediateOrder | forward | forward, reverse, or random |

spinTo(target, options?) returns Promise<boolean>. It resolves false when cancelled, aborted, or invalid. cancel(), pause(), and resume() control an active cell spin; boards call them automatically.

The default motion advances through adjacent reel values at a readable mechanical cadence. To preserve reel order and coordinated settling, the board may tune the preferred cadence within a restrained range or add a complete revolution. Cells spin concurrently, and longer paths naturally show more flaps. Set spinDuration: 0 for an immediate settle.

Sequences and boards

Assign frames through the JavaScript-only sequence property. Each frame needs a values record keyed by cell name; partial frames are allowed.

board.sequence = [
  {
    values: { gate: "A", status: "BOARDING" },
    hold: 2400,
    settleOrder: "forward",
    stagger: 120,
    timing: { spinDuration: 1400, flipDuration: 140 },
  },
  {
    values: { gate: "C", status: "LAST CALL" },
    timing: {
      status: { spinDuration: 2100, intermediateOrder: "reverse" },
    },
  },
];

Frame defaults are a 2400 ms hold, forward settle order, and 120 ms minimum gap between settle groups. timing may be one CellTiming object or a record keyed by cell name.

Settle orders are forward, reverse, simultaneous, center-out, edges-in, or a custom array of cell indexes. Center-out and edges-in settle symmetric pairs together. Nested indexes form custom groups; omitted cells are appended in document order:

{
  settleOrder: [[0, 1], [2, 3], 4];
}

All targeted cells begin before the first ordered settle. The board lengthens later groups as needed; it does not run cells serially.

Board API

Boolean attributes/properties are autoplay, loop, and announce. autoplay also works when sequence is assigned after the board connects. announce enables polite announcements only after a complete frame settles.

Read-only properties are cells, currentFrame, and playbackState. Playback methods are:

await board.play();
board.pause();
board.resume();
board.stop();
await board.replay();
await board.next();
await board.previous();
await board.seek(2);

Pausing freezes active flaps and hold timers. stop() cancels active work and leaves the displayed values where they stopped.

Events

Every event bubbles and is composed, so applications can listen on the board or document without reaching into Shadow DOM.

| Event | Detail boundary | | -------------------- | --------------------------------------------------------------- | | sfe-flip-start | Cell starts moving; includes cell, name, target, previous value | | sfe-flip | One intermediate flap; includes current transition values | | sfe-settle | Cell reaches its target | | sfe-frame-start | A validated frame starts | | sfe-frame-settle | All targeted cells settle | | sfe-sequence-start | Playback starts | | sfe-sequence-end | Non-looping playback ends | | sfe-playback-state | State becomes idle, playing, paused, or stopped | | sfe-config-error | Invalid reel, target, frame, sequence, or seek boundary |

Sound is intentionally external:

board.addEventListener("sfe-flip", () => {
  void flapAudio.play().catch(() => {});
});

Styling

Both elements use open Shadow DOM. Custom properties inherit from the board into its cells.

| Custom property | Default | | ------------------------ | --------------------------- | | --sfe-board-background | #0c0d0e | | --sfe-board-padding | 0.7rem | | --sfe-board-gap | 0.12rem | | --sfe-board-radius | 0.22rem | | --sfe-board-border | subtle 1 px border | | --sfe-font-family | system monospace stack | | --sfe-font-size | 1rem | | --sfe-font-weight | 700 | | --sfe-letter-spacing | -0.04em | | --sfe-value-size | 1.35em | | --sfe-cell-width | 1.9em | | --sfe-cell-height | 2.5em | | --sfe-cell-background | #17191b | | --sfe-cell-color | #f3f1e8 | | --sfe-cell-border | subtle 1 px border | | --sfe-cell-radius | 0.08em | | --sfe-cell-shadow | dark drop shadow | | --sfe-split-line | dark split line | | --sfe-step-duration | managed from flipDuration |

sfe-board {
  --sfe-board-background: #0b0c0d;
  --sfe-cell-background: #1b1d1f;
  --sfe-cell-color: #f5f1e8;
  --sfe-cell-width: 2em;
  --sfe-cell-height: 2.7em;
}

sfe-cell::part(split-line) {
  opacity: 0.65;
}

Parts are board, grid, cell, top, bottom, moving-top, moving-bottom, and split-line.

Accessibility and browser support

• prefers-reduced-motion: reduce removes intermediate flips and settles directly.
• Each cell exposes one accessible value; duplicated mechanical layers are hidden from assistive technology.
• Intermediate reel values are not announced.
• announce opts a board into an atomic polite live region after each settled frame; adjacent single-character cells are announced as normal words.
• Demo and builder controls use native keyboard controls and visible focus styles.
• Current Chromium, Firefox, and WebKit are tested. The package requires Custom Elements, Shadow DOM, CSS custom properties, private class fields, and ES modules.

Development and releases

npm ci
npm run validate

See CONTRIBUTING.md, SECURITY.md, and the maintainer release runbook. Releases use Conventional Commits and Release Please; npm publication remains disabled until trusted publishing is configured.

License

MIT © Gabe Albert