View Transitions

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

Enabling View Transitions

Set useViewTransitions: true 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. Use these types to 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.

Target these types 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

Assign a custom transitionType to an individual route to select 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.