View Transitions

The View Transitions API animates changes between application views. Retend’s router can use this API for route changes.

Enabling View Transitions

useViewTransitions: true is set when creating the Router:

import { Router, defineRoutes } from 'retend';

const routes = defineRoutes(() => [
  { path: '/', component: Home },
  { path: '/about', component: About },
]);

export function createRouter() {
  return new Router({
    routes,
    useViewTransitions: true,
  });
}

When enabled, the router wraps each route change in document.startViewTransition(). If the browser does not support the API, the router uses immediate navigation.

Automatic Direction Types

The router determines the navigation direction and adds a type to the view transition. These types define different animations for forward and backward navigation:

• forwards — Navigating to a new page.
• backwards — Navigating back in the history stack.
• neutral — Replacing the current page or navigating to the same path.

These types are targeted in CSS:

@keyframes slide-in-from-right {
  from {
    transform: translateX(100%);
  }
  to {
    transform: translateX(0);
  }
}

@keyframes slide-out-to-left {
  from {
    transform: translateX(0);
  }
  to {
    transform: translateX(-100%);
  }
}

::view-transition-group(forwards) {
  animation: slide-in-from-right 300ms ease;
}

::view-transition-old(forwards) {
  animation: slide-out-to-left 300ms ease;
}

Per-Route Transition Types

A custom transitionType assigned to an individual route selects a transition for that route:

const routes = defineRoutes(() => [
  { path: '/', component: Home },
  {
    path: '/gallery',
    component: Gallery,
    transitionType: 'gallery',
  },
  {
    path: '/settings',
    component: Settings,
    transitionType: 'settings',
  },
]);

The per-route transitionType is added alongside the direction type. Both types are available to CSS:

::view-transition-group(gallery) {
  animation: fade-zoom-in 400ms ease;
}

::view-transition-group(settings) {
  animation: slide-up 250ms ease;
}

This allows CSS to select transitions by route and navigation direction.