use-view-transition

Animate DOM updates with the View Transition API.


Package	`@vizejs/composable/use-view-transition`
Own the source	`vize lib pull composable:use-view-transition`
Runtime exports	`useViewTransition`
Gzip budget	2560 B

Usage

import { useViewTransition } from "@vizejs/composable/use-view-transition";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useViewTransition`	dom	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`window`	`tryOnScopeDispose`, `useReducedMotion`

API

`useViewTransition`

Animate DOM updates with the View Transition API. Starting a new transition skips the running one (browser behavior). The running transition is skipped when the owning reactive scope stops. Server rendering: start runs the update directly; supported and isTransitioning are false.

function useViewTransition(options: UseViewTransitionOptions = {}): ViewTransitionControls

const { start } = useViewTransition();
await start(async () => {
  page.value = next;
  await nextTick();
}, { types: ["forward"] });

Types

`ViewTransitionLike`

Minimal ViewTransition.

Member	Type	Description
`finished`	`Promise<void>`	Settles when the transition animation finished (or was skipped).
`ready`	`Promise<void>`	Resolves when the animation is about to start; rejects when skipped.
`updateCallbackDone`	`Promise<void>`	Settles when the update callback settled.
`skipTransition`	`() => void`	Skip the animation; the update still runs.

`ViewTransitionDocumentHost`

Minimal document consumed by useViewTransition.

Member	Type	Description
`startViewTransition`	`(update?: StartViewTransitionArgument) => ViewTransitionLike`	Start a same-document view transition.

`UseViewTransitionOptions`

Options for useViewTransition.

Member	Type	Description
`document`?	`MaybeRefOrGetter<ViewTransitionDocumentHost \| null \| undefined>`	Document for alternate runtimes and tests.
`respectReducedMotion`?	`boolean`	Run updates without a transition while reduced motion is preferred.
`reducedMotion`?	`MaybeRefOrGetter<boolean>`	Whether reduced motion is preferred.

`ViewTransitionStartOptions`

Per-call options of ViewTransitionControls.start.

Member	Type	Description
`types`?	`readonly string[]`	Transition types. Runtimes without typed transitions fall back to an untyped transition.

`ViewTransitionControls`

Reactive state and actions returned by useViewTransition.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether `document.startViewTransition` is available.
`transition`	`ComputedRef<ViewTransitionLike \| null>`	The running transition (the host object itself, not a readonly proxy, so native methods keep working), cleared once it finished.
`isTransitioning`	`Readonly<ShallowRef<boolean>>`	Whether a transition started by this composable is running.
`start`	`<Result>( update: () => Result \| PromiseLike<Result>, options?: ViewTransitionStartOptions, ) => Promise<Result>`	Run `update` inside a view transition, or directly when unsupported or reduced motion is preferred.
`skip`	`() => void`	Skip the running transition's animation.