FOR TAILWIND CSS V4

DOCUMENTATION

Same-document transitions.

One wrapper around your state change, and the browser does the rest.

The half CSS cannot do

View transitions are CSS until the moment the thing that moves is your own application state. A navigation is the browser’s business (@view-transition { navigation: auto } and the two documents are captured for you), but swapping a card, opening a panel, or reordering a list happens inside one document, and the browser cannot see it happen. It needs a before and an after, which means someone has to say when the change is.

Create a transition controller and run the state change through it:

import { createViewTransition } from '@ibnlanre/jumi/view-transition'

const transition = createViewTransition()

transition.run(() => {
  setActive('bravo')
})

The callback is where your change goes, so the browser captures the before and the after around it. The classes from View transitions style what happens next. Nothing else is required: no framework, no state library, and no runtime in the root package: @ibnlanre/jumi stays CSS and build-time, and only the page that changes state imports this subpath.

The callback must finish synchronously

Do not await inside it, do not return a Promise, and do not wait for a frame. This is not a style preference. A promise handed to the browser is a pending callback, and await requestAnimationFrame() inside one wedges the transition permanently: no capture, no animation, no error, and the change never lands. The callback is called once, and it has to be finished when it returns. If your change depends on something asynchronous, do that first and then transition the result:

const next = await load()

transition.run(() => {
  setActive(next)
})

Two calls, and which one wins

Calling it twice while a transition is running is the case worth knowing about, and the default (auto) decides by when the second call arrives. Which is the one thing an accidental duplicate cannot hide:

  • the same task. A second call from the same event, or one that event deferred with a promise, is the same interaction twice: your update runs immediately, and no second transition starts. Nothing is dropped, and the transition the reader is already watching is not cut short. (Whether that update shows up inside the running transition’s snapshots depends on when they were taken: the point is that you do not have to think about it.)
  • a later task. A second click, a keypress, a timer: a new intention, so it supersedes. The move the reader just asked for happens now, and the transition in flight is replaced by it.

So a duplicate handler is harmless and a rapid second gesture is answered, without either case becoming your problem. Override it only when you know something the timing does not:

// a poll or a resize writing on a schedule: never a second transition per write
const backgroundUpdates = createViewTransition({ concurrency: 'coalesce' })
backgroundUpdates.run(update)

// override a controller's policy for this call
transition.run(update, { concurrency: 'supersede' })

The result, if you want it

The call resolves to an outcome instead of rejecting whenever the transition could not run. Most callers fire it and ignore the result; branch on it when the difference matters, such as reporting why nothing animated, the outcome is a discriminated union, so reason exists only on the branch where nothing ran:

const result = await transition.run(() => {
  setOpen(true)
})

if (result.transitioned) {
  console.log('the change animated')
} else {
  // narrowed: `reason` exists here, and nowhere else
  console.log(result.reason)
}
result meaning
{ transitioned: true } the transition ran, with your change inside its boundary
{ transitioned: false, reason: 'in-flight' } a duplicate call in the same interaction
{ transitioned: false, reason: 'aborted' } replaced or skipped before it animated
{ transitioned: false, reason: 'hidden' } the document is in a background tab
{ transitioned: false, reason: 'unsupported' } this browser has no view transitions

Your update runs exactly once per call in every one of those cases. An outcome describes the animation, never whether your change happened, while update errors and asynchronous callbacks reject rather than becoming platform outcomes.

Reusable operations

Use transition.run(update, options) for a one-off change. For reusable operations, the controller holds shared concurrency policy and each wrapped operation owns its lifecycle:

import { createViewTransition } from '@ibnlanre/jumi/view-transition'

const transition = createViewTransition({ concurrency: 'auto' })
const open = transition.wrap(updateOpen, {
  onTransitionStart() {
    console.log('open transition started')
  },
  onTransitionEnd() {
    console.log('open transition stopped')
  },
  onDecline(reason) {
    console.log('updated without animation', reason)
  },
  onError(error) {
    console.error(error)
  },
})

await open(true)

wrap() preserves the update’s argument types and call receiver, but intentionally replaces its original return value with Promise<ViewTransitionOutcome>. Functional updater arguments are forwarded unchanged. The controller exposes run for one-offs and wrap for reusable operations. Lifecycle hooks belong to the wrapped operation, not the controller.

Hook Meaning
onTransitionStart() The visual transition materialized (ready resolved).
onTransitionEnd() A started transition ceased being active, including being superseded or skipped. This does not promise it reached its visual endpoint.
onDecline(reason) The mutation happened, but no visual transition materialized.
onError(error) The invocation rejected. The hook observes the error; its returned promise still rejects.

Wrapping establishes operation attribution, not invocation attribution. open(true) and open(false) can overlap and invoke the same hooks. Jumi tracks their transitions independently internally; each call’s returned promise is its own outcome channel. A hook alone cannot identify which overlapping call fired. A controller is a configured interface, not an independent transition domain. All controllers in the same module instance coordinate the document’s active transition. Separate controllers can carry different policies, but their transitions still compete. The policy of the incoming call determines how it proceeds.

Update errors reject, including on unsupported, hidden and coalesced paths. With onError, Jumi attaches an observer to that rejection; awaiting the returned promise still throws. A hook’s own exception is reported to the global error handler and does not change the invocation’s outcome.

Framework updates must commit the DOM

A synchronous JavaScript setter does not necessarily commit the DOM synchronously. The wrapped update must finish its DOM changes inside the browser’s update callback. Jumi cannot infer or flush a framework’s rendering schedule.

For React, make the commit boundary explicit:

import { flushSync } from 'react-dom'
import type { SetStateAction } from 'react'
import { createViewTransition } from '@ibnlanre/jumi/view-transition'

const transition = createViewTransition()
const open = transition.wrap((next: SetStateAction<boolean>) => {
  flushSync(() => setOpen(next))
})

await open(true)
await open(previous => !previous)

Use this from an event handler where flushing is supported. wrap(setOpen) alone does not guarantee the new DOM is captured. React’s flushSync documentation explains the constraints and performance tradeoffs. Other frameworks need their equivalent synchronous commit boundary. Async navigation functions are not automatically valid updates: finish asynchronous work first, then wrap the synchronous DOM mutation.

Both APIs reject Promise-returning updates at the TypeScript boundary and at runtime. Neither introduces an asynchronous update mode.

See it together

The layout projection demo ↗ is the whole story on one page: candidates styling the old and new snapshots, a real layout shift, a second click arriving mid-transition, and a switch to the browser’s own behaviour to compare.

Improve these docs ↗