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

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

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

Try it

Animate a layout change

Wrap a state change in a view transition where supported, and apply it directly elsewhere.

Open the interactive example

What to observe: Show as list switches the layout; in supporting browsers the change animates. Reduced motion skips the animation.

Await nextTick() inside the update so the DOM is ready before the new snapshot. respectReducedMotion is on by default.

Compare the initial and interacted states

Animate a layout change: initial state — Initial state

Animate a layout change: state after the verified interactions — After the verified interactions

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { nextTick, ref } from "vue";
import { useViewTransition } from "@vizejs/composable/use-view-transition";

const layout = ref<"grid" | "list">("grid");
const { start } = useViewTransition();

function toggle() {
  void start(async () => {
    layout.value = layout.value === "grid" ? "list" : "grid";
    await nextTick();
  });
}
</script>

<template>
  <div class="composable-example">
    <p>Animate a layout change with a view transition where the browser supports it.</p>
    <button type="button" @click="toggle">Show as {{ layout === "grid" ? "list" : "grid" }}</button>
    <ul
      aria-label="Talks"
      :style="{
        display: layout === 'grid' ? 'grid' : 'block',
        gridTemplateColumns: 'repeat(2, 1fr)',
      }"
    >
      <li>Vapor mode</li>
      <li>Type checking</li>
      <li>Linting</li>
      <li>Formatting</li>
    </ul>
    <output aria-live="polite">Layout: {{ layout }}</output>
  </div>
</template>

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.