feat: add native view transition built-in support

userquin · userquin · commit afdb6e01ab56 · 2025-09-15T18:46:01.000+02:00
diff --git a/packages/router/src/RouterView.ts b/packages/router/src/RouterView.ts
@@ -30,6 +30,7 @@ import {
 import { assign, isArray, isBrowser } from './utils'
 import { warn } from './warning'
 import { isSameRouteRecord } from './location'
+import { transitionModeKey } from './transition'
 
 export interface RouterViewProps {
   name?: string
@@ -62,6 +63,7 @@ export const RouterViewImpl = /*#__PURE__*/ defineComponent({
     __DEV__ && warnDeprecatedUsage()
 
     const injectedRoute = inject(routerViewLocationKey)!
+    const transitionMode = inject(transitionModeKey)!
     const routeToDisplay = computed<RouteLocationNormalizedLoaded>(
       () => props.route || injectedRoute.value
     )
@@ -199,8 +201,11 @@ export const RouterViewImpl = /*#__PURE__*/ defineComponent({
       return (
         // pass the vnode to the slot as a prop.
         // h and <component :is="..."> both accept vnodes
-        normalizeSlot(slots.default, { Component: component, route }) ||
-        component
+        normalizeSlot(slots.default, {
+          Component: component,
+          route,
+          transitionMode,
+        }) || component
       )
     }
   },
diff --git a/packages/router/src/client-router.ts b/packages/router/src/client-router.ts
@@ -0,0 +1,51 @@
+import type { Router } from './router'
+import type {
+  RouterApiOptions,
+  createNavigationApiRouter,
+} from './navigation-api'
+import type { RouterViewTransition, TransitionMode } from './transition'
+
+export interface ClientRouterOptions {
+  /**
+   * Factory function that creates a legacy router instance.
+   * Typically: () => createRouter({ history: createWebHistory(), routes })
+   */
+  legacy: {
+    factory: (transitionMode: TransitionMode) => Router
+  }
+  /**
+   * Options for the new Navigation API based router.
+   * If provided and the browser supports it, this will be used.
+   */
+  navigationApi?: {
+    options: RouterApiOptions
+  }
+  /**
+   * Enable native View Transitions.
+   */
+  viewTransition?: true | RouterViewTransition
+}
+
+export function createClientRouter(options: ClientRouterOptions): Router {
+  let transitionMode: TransitionMode = 'auto'
+
+  if (
+    options?.viewTransition &&
+    typeof document !== 'undefined' &&
+    document.startViewTransition
+  ) {
+    transitionMode = 'view-transition'
+  }
+
+  const useNavigationApi =
+    options.navigationApi && inBrowser && window.navigation
+
+  if (useNavigationApi) {
+    return createNavigationApiRouter(
+      options.navigationApi!.options,
+      transitionMode
+    )
+  } else {
+    return options.legacy.factory(transitionMode)
+  }
+}
diff --git a/packages/router/src/navigation-api/index.ts b/packages/router/src/navigation-api/index.ts
@@ -1,4 +1,4 @@
-import type { App } from 'vue'
+import { App, shallowReactive, unref } from 'vue'
 import { shallowReactive, shallowRef, unref } from 'vue'
 import {
   parseURL,
@@ -59,13 +59,17 @@ import {
   RouterHistory,
 } from '../history/common'
 import { RouteRecordNormalized } from '../matcher/types'
+import { TransitionMode, transitionModeKey } from '../transition'
 
 export interface RouterApiOptions extends Omit<RouterOptions, 'history'> {
   base?: string
   location: string
 }
 
-export function createNavigationApiRouter(options: RouterApiOptions): Router {
+export function createNavigationApiRouter(
+  options: RouterApiOptions,
+  transitionMode: TransitionMode = 'auto'
+): Router {
   const matcher = createRouterMatcher(options.routes, options)
   const parseQuery = options.parseQuery || originalParseQuery
   const stringifyQuery = options.stringifyQuery || originalStringifyQuery
@@ -789,6 +793,10 @@ export function createNavigationApiRouter(options: RouterApiOptions): Router {
     replace: (to: RouteLocationRaw) => navigate(to, { replace: true }),
   }
 
+  let beforeResolveTransitionGuard: (() => void) | undefined
+  let afterEachTransitionGuard: (() => void) | undefined
+  let onErrorTransitionGuard: (() => void) | undefined
+
   const router: Router = {
     currentRoute,
     listening: true,
@@ -817,6 +825,70 @@ export function createNavigationApiRouter(options: RouterApiOptions): Router {
     onError: errorListeners.add,
     isReady,
 
+    enableViewTransition(options) {
+      beforeResolveTransitionGuard?.()
+      afterEachTransitionGuard?.()
+      onErrorTransitionGuard?.()
+
+      if (typeof document === 'undefined' || !document.startViewTransition) {
+        return
+      }
+
+      const defaultTransitionSetting =
+        options.transition?.defaultViewTransition ?? true
+
+      let finishTransition: (() => void) | undefined
+      let abortTransition: (() => void) | undefined
+
+      const resetTransitionState = () => {
+        finishTransition = undefined
+        abortTransition = undefined
+      }
+
+      beforeResolveTransitionGuard = this.beforeResolve(
+        (to, from, next, info) => {
+          const transitionMode =
+            to.meta.viewTransition ?? defaultTransitionSetting
+          if (
+            info?.isBackBrowserButton ||
+            info?.isForwardBrowserButton ||
+            transitionMode === false ||
+            (transitionMode !== 'always' &&
+              window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+          ) {
+            next(true)
+            return
+          }
+
+          const promise = new Promise<void>((resolve, reject) => {
+            finishTransition = resolve
+            abortTransition = reject
+          })
+
+          const transition = document.startViewTransition(() => promise)
+
+          options.onStart?.(transition)
+          transition.finished
+            .then(() => options.onFinished?.(transition))
+            .catch(() => options.onAborted?.(transition))
+            .finally(resetTransitionState)
+
+          next(true)
+
+          return promise
+        }
+      )
+
+      afterEachTransitionGuard = this.afterEach(() => {
+        finishTransition?.()
+      })
+
+      onErrorTransitionGuard = this.onError((error, to, from) => {
+        abortTransition?.()
+        resetTransitionState()
+      })
+    },
+
     install(app) {
       app.component('RouterLink', RouterLink)
       app.component('RouterView', RouterView)
@@ -859,6 +931,7 @@ export function createNavigationApiRouter(options: RouterApiOptions): Router {
       app.provide(routerKey, router)
       app.provide(routeLocationKey, shallowReactive(reactiveRoute))
       app.provide(routerViewLocationKey, currentRoute)
+      app.provide(transitionModeKey, transitionMode)
 
       const unmountApp = app.unmount
       installedApps.add(app)
diff --git a/packages/router/src/router-factory.ts b/packages/router/src/router-factory.ts
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
@@ -69,6 +69,11 @@ import { addDevtools } from './devtools'
 import { _LiteralUnion } from './types/utils'
 import { RouteLocationAsRelativeTyped } from './typed-routes/route-location'
 import { RouteMap } from './typed-routes/route-map'
+import {
+  RouterViewTransition,
+  TransitionMode,
+  transitionModeKey,
+} from './transition'
 
 /**
  * Internal type to define an ErrorHandler
@@ -205,6 +210,15 @@ export interface Router {
    */
   listening: boolean
 
+  /**
+   * Enable native view transition.
+   *
+   * NOTE: will be a no-op if the browser does not support it.
+   *
+   * @param options The options to use.
+   */
+  enableViewTransition(options: RouterViewTransition)
+
   /**
    * Add a new {@link RouteRecordRaw | route record} as the child of an existing route.
    *
@@ -216,6 +230,7 @@ export interface Router {
     parentName: NonNullable<RouteRecordNameGeneric>,
     route: RouteRecordRaw
   ): () => void
+
   /**
    * Add a new {@link RouteRecordRaw | route record} to the router.
    *
@@ -382,7 +397,10 @@ export interface Router {
  *
  * @param options - {@link RouterOptions}
  */
-export function createRouter(options: RouterOptions): Router {
+export function createRouter(
+  options: RouterOptions,
+  transitionMode: TransitionMode = 'auto'
+): Router {
   const matcher = createRouterMatcher(options.routes, options)
   const parseQuery = options.parseQuery || originalParseQuery
   const stringifyQuery = options.stringifyQuery || originalStringifyQuery
@@ -1230,6 +1248,11 @@ export function createRouter(options: RouterOptions): Router {
   let started: boolean | undefined
   const installedApps = new Set<App>()
 
+  let beforeResolveTransitionGuard: (() => void) | undefined
+  let afterEachTransitionGuard: (() => void) | undefined
+  let onErrorTransitionGuard: (() => void) | undefined
+  let popStateListener: (() => void) | undefined
+
   const router: Router = {
     currentRoute,
     listening: true,
@@ -1255,6 +1278,26 @@ export function createRouter(options: RouterOptions): Router {
     onError: errorListeners.add,
     isReady,
 
+    enableViewTransition(options) {
+      beforeResolveTransitionGuard?.()
+      afterEachTransitionGuard?.()
+      onErrorTransitionGuard?.()
+      if (popStateListener) {
+        window.removeEventListener('popstate', popStateListener)
+      }
+
+      if (typeof document === 'undefined' || !document.startViewTransition) {
+        return
+      }
+
+      ;[
+        beforeResolveTransitionGuard,
+        afterEachTransitionGuard,
+        onErrorTransitionGuard,
+        popStateListener,
+      ] = enableViewTransition(this, options)
+    },
+
     install(app: App) {
       app.component('RouterLink', RouterLink)
       app.component('RouterView', RouterView)
@@ -1293,6 +1336,7 @@ export function createRouter(options: RouterOptions): Router {
       app.provide(routerKey, router)
       app.provide(routeLocationKey, shallowReactive(reactiveRoute))
       app.provide(routerViewLocationKey, currentRoute)
+      app.provide(transitionModeKey, transitionMode)
 
       const unmountApp = app.unmount
       installedApps.add(app)
@@ -1356,3 +1400,94 @@ function extractChangingRecords(
 
   return [leavingRecords, updatingRecords, enteringRecords]
 }
+
+function isChangingPage(
+  to: RouteLocationNormalized,
+  from: RouteLocationNormalized
+) {
+  if (to === from || from === START_LOCATION) {
+    return false
+  }
+
+  // If route keys are different then it will result in a rerender
+  if (generateRouteKey(to) !== generateRouteKey(from)) {
+    return true
+  }
+
+  const areComponentsSame = to.matched.every(
+    (comp, index) =>
+      comp.components &&
+      comp.components.default === from.matched[index]?.components?.default
+  )
+  return !areComponentsSame
+}
+
+function enableViewTransition(router: Router, options: RouterViewTransition) {
+  let transition: undefined | ViewTransition
+  let hasUAVisualTransition = false
+  let finishTransition: (() => void) | undefined
+  let abortTransition: (() => void) | undefined
+
+  const defaultTransitionSetting =
+    options.transition?.defaultViewTransition ?? true
+
+  const resetTransitionState = () => {
+    transition = undefined
+    hasUAVisualTransition = false
+    abortTransition = undefined
+    finishTransition = undefined
+  }
+
+  function popStateListener(event: PopStateEvent) {
+    hasUAVisualTransition = event.hasUAVisualTransition
+    if (hasUAVisualTransition) {
+      transition?.skipTransition()
+    }
+  }
+
+  window.addEventListener('popstate', popStateListener)
+
+  const beforeResolveTransitionGuard = router.beforeResolve((to, from) => {
+    const transitionMode = to.meta.viewTransition ?? defaultTransitionSetting
+    if (
+      hasUAVisualTransition ||
+      transitionMode === false ||
+      (transitionMode !== 'always' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches) ||
+      !isChangingPage(to, from)
+    ) {
+      return
+    }
+
+    const promise = new Promise<void>((resolve, reject) => {
+      finishTransition = resolve
+      abortTransition = reject
+    })
+
+    const transition = document.startViewTransition(() => promise)
+
+    options.onStart?.(transition)
+    transition.finished
+      .then(() => options.onFinished?.(transition))
+      .catch(() => options.onAborted?.(transition))
+      .finally(resetTransitionState)
+
+    return promise
+  })
+
+  const afterEachTransitionGuard = router.afterEach(() => {
+    finishTransition?.()
+  })
+
+  const onErrorTransitionGuard = router.onError(() => {
+    abortTransition?.()
+    resetTransitionState()
+  })
+
+  return [
+    beforeResolveTransitionGuard,
+    afterEachTransitionGuard,
+    onErrorTransitionGuard,
+    popStateListener,
+  ]
+}
diff --git a/packages/router/src/transition.ts b/packages/router/src/transition.ts
