vue-view-transitions v1.2.1

vue-view-transitions

A simple tool to use View Transition API in Vue

Introduction

The View Transitions API is an experimental API recently released in Chrome 111+. It provides a convenient way to create animated transitions between different DOM states. vue-view-transitions makes it easier to use View Transitions API in Vue. For more information about View Transition API, Please check Reference.

Install

npm i vue-view-transitions

Or

pnpm add vue-view-transitions

yarn add vue-view-transitions

Usage

Use ViewTransitionsPlugin to add view transition name easily

ViewTransitionsPlugin provides a directive v-view-transition-name (or v-trans for short) to apply view-transition-name to elments. You should use a unique view-transition-name for each element (or element pair).

In main.ts

import { createApp } from 'vue'
import { ViewTransitionsPlugin } from 'vue-view-transitions'
import App from './App.vue'

createApp(App).use(ViewTransitionsPlugin())

In App.vue

<h1 v-view-transition-name="'title'">Title</h1>

It will be rendered to this when mounted:

<h1 style="view-transition-name: title">Title</h1>

You can use object syntax to toggle it dynamically:

<h1 v-trans="{ title: someBoolean }">Title</h1>

Use startViewTransition to start a new view transition

async function animate() {
    const viewTransition = startViewTransition()
    await viewTransition.captured
    style.value.transform = style.value.transform === '' ? 'translateX(50px)' : ''
}

Note that you should wait viewTransition.captured to be fulfilled before making dom updates. Otherwise the dom change may finish before the browser can capture the snapshot of current state and results in no transitions at all.

Use startViewTransition in vue-router to apply page transitions

The code execution order here is a bit puzzling due to the asynchronous nature of both view transitions and routing. The order should be "beforeResolve start" -> "capture screenshot of current state" -> "beforeResolve end" -> "dom change callback" -> "view transition". As you can see, there are two promises: beforeResolve waits for the viewTransition.captured promise to fulfill, startViewTransition waits for the dom change callback to fulfill.

router.beforeResolve(async () => {
    const viewTransition = startViewTransition(async () => {
        // dom changes
    })
    await viewTransition.captured
    // ...
})

ViewTransition object

startViewTransition(callback?): return a ViewTransition object. The optional callback is supposed to return a promise. When the promise returned by the callback fulfills, the view transition starts. A few properties are used to describe the whole process. They fulfills in a sequential order: captured -> updateCallbackDone -> ready -> finished.

• ViewTransition.captured: A promise that fulfills once user agent finishes capturing a screenshot of the current state

• ViewTransition.updateCallbackDone: A promise that fulfills once the promise returned by the callback of startViewTransition fulfills

• ViewTransition.ready: A Promise that fulfills once the pseudo-element tree is created and the transition animation is about to start.

• ViewTransition.finished: A Promise that fulfills once the transition animation is finished, and the new page view is visible and interactive to the user.

• ViewTransition.skipTransition(): A method used to skips the animation part of the view transition.

Use in Nuxt

Nuxt ships with an experimental support for the native View Transitions API since 3.4.0. vue-view-transitions provides a nuxt module for nuxt users. Here is how to enable it:

export default defineNuxtConfig({
    modules: [
        'vue-view-transitions/nuxt'
    ],
    experimental: {
        viewTransition: true
    }
})

Done. Now it's able to use page transitions with the v-trans directive during page routing without any extra work thanks to the nuxt intergration. As for the manual triggered transitions, it works the same as described above.

Examples

More examples are available here.

Compatibility

Vue 2

vue-view-transitions supports vue 2.6 or above. You should use ViewTransitionsLegacyPlugin instead of ViewTransitionsPlugin in Vue 2 project.

import { ViewTransitionsLegacyPlugin } from 'vue-view-transitions'

Vue.use(ViewTransitionsLegacyPlugin())

Browser Compatibility

vue-view-transitions uses View Transitions API under the hood. Currently, View Transitions API is only available in Chrome 111+. If running in unsupported browsers, it simply executes the callback of startViewTransition (if provided). If you need a more compatible solution, use vue-starport, or nuxt transitions if you are using Nuxt. (Browser compatibility)

Migrate from 0.x

startViewTransition no longer return a promise.

Previous:

await startViewTransition()

Now:

const viewTransition = startViewTransition()
await viewTransition.captured

Changelog

See CHANGELOG

Reference

Smooth and simple transitions with the View Transitions API

MDN ViewTransition

Acknowledgment

If you found it useful somehow, I would be grateful if you could leave a star in the project's GitHub repository.

Thank you.