Swap

Animated content swaps for a region: tabs, pagination, filtered lists. The ink covers the old content, your code changes the DOM underneath, the new content is revealed. The height follows, and focus lands on the new content.

Live example

Page 1. Less, but better.

Usage

import { createRenderer, createSwapFx } from 'webgl-ui'

const renderer = createRenderer()
const results = document.querySelector<HTMLElement>('#results')!
const swap = createSwapFx(results, { renderer })

async function showPage(n: number) {
  const html = await fetchPage(n)            // anything: fetch, template, framework render
  await swap.run(() => { results.innerHTML = html })
}

The region's background is the cover color (or set --fx-cover). The update may be sync or async; while it runs, the region stays covered.

Options

Option	Type	Default	Description
`renderer`	`Renderer \| () => Renderer`	required	The shared renderer.
`effect`	`EffectDef`	`inkEffect`	Any cover effect.
`duration`	`number`	`600`	Reveal in ms; covering takes 60%.
`viewTransition`	`boolean`	`false`	Run the update inside `document.startViewTransition()` where it exists: the browser morphs the region's box and cross-fades the rest of the page. Otherwise the library animates the height itself, in every engine.

Returns

Member	Description
`run(update)`	Covers, runs `update`, reveals. Calls are queued; the promise resolves after the reveal.
`destroy()`	Cancels a running animation; later calls just run the update.

Behavior and accessibility

The DOM change is yours and happens at once, under the cover: nothing is cloned or faked.
If focus was inside the region and the update removed it, focus moves to the region (made focusable with tabindex="-1"), so the next Tab continues in the new content. View transitions do not do this by themselves.
Announcing the change is your call: aria-live="polite" on the region, as in the example, or a status message.
A failing update uncovers the region and leaves it as it was.
Reduced motion and the other preferences, or no WebGL2: the update runs immediately, focus is still handled.