data-transition

Declarative View Transitions API integration. Marks elements that morph, slide, or fade during state changes.

Overview

The data-transition attribute marks elements that participate in View Transitions. Unlike data-effect (ambient animation), data-transition describes state-change moments — navigation, DOM swaps, route changes.

VB auto-assigns view-transition-name and optional view-transition-class so the browser's View Transition API handles the animation.

Mental model

Two attribute systems, two purposes:

IntentAttributeWhen
Ambient animationdata-effectScroll, hover, load
State changedata-transitionDOM updates, navigation
<!-- Ambient: decorative, repeatable --> <p data-effect="fade-in" data-trigger="scroll"> <!-- State change: meaningful, navigational --> <img data-transition="morph"> <main data-transition="slide"> <ul data-transition="stagger">

morph

The element morphs between its old and new state. The browser interpolates position, size, and appearance. Ideal for images, cards, and shared elements across views.

<!-- List view --> <img src="photo.jpg" data-transition="morph"> <!-- Detail view (same element or matched by view-transition-name) --> <img src="photo.jpg" data-transition="morph">

VB assigns view-transition-name: morph-{uid} automatically. Use id for stable names or let VB generate one.

slide

Page-level slide animation. The old content slides out while new content slides in.

<main data-transition="slide"> <!-- Page content swaps with a slide animation --> </main>

fade

Explicit crossfade without position morphing. Good for content areas that shouldn't move.

<article data-transition="fade"> <!-- Content cross-fades on swap --> </article>

scale

Scale-down/scale-up swap effect.

<section data-transition="scale">...</section>

stagger

Children get individual view-transition-name values so they can reorder, add, or remove with staggered timing.

<ul data-transition="stagger"> <li>Item 1</li> <li>Item 2</li> <li>Item 3</li> </ul>

none

Instant swap with no animation. Opt out a specific section from the page-level transition.

<nav data-transition="none"> <!-- Navigation stays static during page transitions --> </nav>

VB.swap()

Wrap any DOM mutation in a View Transition. Falls back gracefully when the API isn't supported.

VB.swap(() => { // DOM mutations here — the browser captures before/after snapshots document.querySelector('main').innerHTML = newContent; });

Custom transitions

Register custom transition types via VB.transition().

VB.transition('flip', (el) => { el.style.viewTransitionName = 'flip-' + VB.uid(el); el.style.viewTransitionClass = 'flip'; return () => { el.style.viewTransitionName = ''; el.style.viewTransitionClass = ''; }; }); <section data-transition="flip">...</section>

Combining with effects

Both systems compose on the same element. data-effect handles ambient animation while data-transition handles state changes.

<section data-effect="fade-in slide-up" data-trigger="scroll" data-transition="morph" data-stagger="80ms" class="slow" > <!-- Scroll-triggered entrance + morphs during navigation --> </section>

Browser support

View Transitions require Chrome 111+ or Safari 18+. In unsupported browsers, VB.swap() falls back to calling the update function directly — the DOM change happens instantly, no error.

API reference

TransitionCSS ClassDescription
morph(default crossfade)Position + size + appearance morph between states.
slideslide-leftHorizontal slide out/in.
fadefadeCrossfade without position interpolation.
scalescaleScale-down/scale-up swap.
staggerfadeChildren get individual names for list reorder transitions.
nonenoneInstant swap, no animation.
JS MethodSignatureDescription
VB.transition()(name, handler) => voidRegister a custom transition type.
VB.swap()(update) => ViewTransition?Wrap DOM mutations in a View Transition.
VB.uid()(el) => stringStable unique ID for view-transition-name generation.