mirror of
https://github.com/jackyzha0/quartz.git
synced 2025-12-19 10:54:06 -06:00
64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
---
|
|
title: "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](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_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:
|
|
|
|
```scss title="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](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using#customizing_your_animations).
|
|
|
|
### Programmatic Transitions
|
|
|
|
When [[creating components|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.
|
|
|
|
```typescript
|
|
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 the browser is supported, otherwise it will fallback to eager execution.
|
|
|
|
## 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`
|
|
|
|
```typescript title="quartz.config.ts"
|
|
const config: QuartzConfig = {
|
|
configuration: {
|
|
// ...
|
|
enableSPA: true,
|
|
enableViewTransitions: true,
|
|
// ...
|
|
},
|
|
}
|
|
```
|