vt-helper

Why

document.startViewTransition is great, but every call site ends up rewriting the same feature-detection boilerplate. vt-helper wraps it once so your code looks the same whether or not the browser supports it — on unsupported browsers your DOM update still runs, you just lose the animation.

There's no shortage of View Transitions tooling, but most of it is either a low-level toolkit or locked to one framework. vt-helper is neither: it's a tiny, framework-agnostic wrapper focused on one job — making startViewTransition and multi-step sequencing safe to call everywhere, with zero dependencies.

vt-helper fills the gap between "copy a snippet from Chrome's docs" and "adopt a whole toolkit or framework binding":

• Framework-agnostic — plain DOM API, works with React, Vue, Svelte, or vanilla JS
• Zero dependencies — nothing to audit, nothing to pull in transitively
• Same shape, always — the fallback returns a TransitionHandle with the same finished / ready / updateCallbackDone / skipTransition() shape as the native ViewTransition, so calling code never branches on support
• Sequencing built in — transitionSequence() chains steps without overlap, which the native API and most wrappers leave for you to implement
• Small and typed — a couple hundred lines of TypeScript, fully typed, tree-shakeable

Install

npm install vt-helper

import { transition } from 'vt-helper';

button.addEventListener('click', () => {
  transition(() => {
    document.body.classList.toggle('dark');
  });
});

Live examples

These demos run vt-helper loaded straight from a CDN, right here in the page.

import { transition } from 'vt-helper';

card.style.viewTransitionName = 'demo-toggle'; // scope the animation

button.addEventListener('click', () => {
  transition(() => {
    card.classList.toggle('dark');
  });
});

button.addEventListener('click', () => {
  transition(() => {
    list.append(list.firstElementChild); // move first item to the end
  });
});

import { transitionSequence } from 'vt-helper';

await transitionSequence([
  () => setStep(1),
  () => setStep(2),
  () => setStep(3),
]);

API reference

Wraps document.startViewTransition(callback). callback may be sync or return a Promise. On unsupported browsers, runs callback via requestAnimationFrame (falling back to a microtask outside the DOM) and returns a handle whose promises resolve once the callback settles.

interface TransitionHandle {
  readonly finished: Promise<void>;
  readonly ready: Promise<void>;
  readonly updateCallbackDone: Promise<void>;
  skipTransition(): void;
}

On unsupported browsers, ready, finished, and updateCallbackDone all resolve (or reject) together once callback settles, and skipTransition() is a no-op.

Runs an array of TransitionCallbacks in order, calling transition() for each and awaiting its finished promise before starting the next. If a step throws or rejects, the sequence stops and the returned promise rejects with that error.

Feature-detects document.startViewTransition. Useful if you want to branch your own logic instead of relying on the built-in fallback.

Browser support

The View Transitions API is supported in recent Chromium-based browsers; see caniuse for current coverage. Everywhere else, vt-helper's fallback runs your callback with no animation, so your DOM updates are consistent across all browsers — you only lose the transition effect, never the update itself.