View Transitions

View Transitions provide smooth, animated page transitions when navigating between pages in Quartz. This progressively enhances the SPA Routing experience by utilizing the browser-native View Transitions API where available.

When navigating between pages, if the View Transitions API is supported and enabled, Quartz will wrap the content update in a view transition. This creates smooth, customizable animations as the page content changes, providing a more polished and app-like experience.

Under the hood, Quartz uses SPA Routing to intercept link clicks and perform client-side navigation. The View Transitions feature builds on top of this by wrapping the DOM updates in document.startViewTransition(), allowing the browser to automatically animate the changes between the old and new page states.

Info

View Transitions require SPA Routing to be enabled in the configuration. Browsers that don’t support the View Transitions API will fall back to instant page updates without animations.

Customization

Quartz assigns appropriate view-transition-name properties to its component, allowing you to create custom animations for different parts of the page.

Styling Transitions

You can customize the behavior of these transitions by adding CSS to your quartz/styles/custom.scss file. For example:

quartz/styles/custom.scss

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.5s;
}

For more advanced customization options, see the MDN documentation on customizing view transition animations.

Programmatic Transitions

When creating your own components, you can use the startViewTransition utility function to wrap DOM updates in a view transition. This ensures your custom scripts respect your view transition settings.

import { startViewTransition } from "./scripts/util"
 
// Wrap your DOM update in a view transition
startViewTransition(() => {
  // Your DOM updates here
  element.textContent = "New content"
})

The startViewTransition function will automatically use the View Transitions API if it’s supported and enabled, or fall back to immediate execution otherwise.

Configuration

View Transitions require both SPA Routing and the View Transitions feature to be enabled in the configuration:

1. Enable SPA Routing: set the enableSPA field to true
2. Enable View Transitions: set the enableViewTransitions field to true

quartz.config.ts

const config: QuartzConfig = {
  configuration: {
    // ...
    enableSPA: true,
    enableViewTransitions: true,
    // ...
  },
}