Transitions
The built-in effects, and how to set the origin, direction, duration and easing, with the cases where the theme switches instantly.
A theme change runs inside document.startViewTransition. The browser snapshots the page before and after, and nuxt-penumbra animates the two snapshots with the Web Animations API. The theme changes at the start; the animation only decides how the new one is revealed.
Built-in effects
| Name | What it does |
|---|---|
circle (default) |
The new theme grows as a circle from the origin until it covers the screen. |
circle-inverse |
The old theme shrinks to the origin as a circle and uncovers the new one below. |
fade |
The old theme fades out while the new one fades in. The origin is ignored. |
wipe |
A straight edge sweeps across the screen in the chosen direction. No origin. |
diamond |
The new theme grows as a diamond from the origin. |
iris |
The new theme opens as a hexagon from the origin, like a camera iris. |
blinds |
Eight slats open side by side, growing in the chosen direction. No origin. |
blur-circle |
Like circle, and the new theme sharpens from a blur while it opens. |
star |
The new theme grows as a five-pointed star from the origin. |
diagonal |
A slanted edge sweeps across the screen in the chosen direction. No origin. |
diagonal-soft |
A diagonal sweep with a feathered edge, in the chosen direction. No origin. |
split |
The new theme opens from the middle outward. direction sets the axis. |
scan |
Forty thin slats reveal the new theme like a scan line. No origin. |
slide |
The new theme pushes the old one off the screen in the chosen direction. |
zoom |
The old theme shrinks away as the new one settles in from slightly larger. |
square |
The new theme grows as a square from the origin. |
triangle |
The new theme grows as a triangle from the origin. |
sunburst |
The new theme bursts out as a twelve-point sun. |
cross |
The new theme grows as a plus sign. |
heart |
The new theme grows as a heart. |
ripple |
Rings spread from the origin and merge into the new theme. |
clock |
A radial sweep, one clockwise turn around the origin. |
curtain |
Two shutters close in from opposite edges. |
stairs |
Ten columns or rows grow one after the other. |
mosaic |
A grid of squares opens in a scattered order. |
blur |
Both themes blur while they cross-fade. |
flip |
The page turns like a card around the axis of direction. |
spin |
The new theme spins and grows in from nothing. |
cover |
The new theme slides in over the old one. |
reveal |
The old theme slides away and uncovers the new one. |
The effects come from @penumbra/core, the engine shared with astro-eclipse. The table lists what is registered. The checks described in browser support did not review the look of each effect one by one.
Direction
direction is 'right' (the default), 'left', 'down' or 'up'. It sets where wipe, diagonal, diagonal-soft, scan, slide, stairs, cover and reveal travel, which way flip turns, and which way the blinds slats grow: 'left' and 'right' give vertical slats, 'up' and 'down' give horizontal ones. For split and curtain, 'left' and 'right' open from a vertical center line, 'up' and 'down' from a horizontal one.
const { setTheme } = usePenumbra()
setTheme('dark', { transition: 'wipe', direction: 'down' })
On the component, pass it as a prop:
<PenumbraToggle transition="wipe" direction="down" />
Choose an effect
Set the default for the whole site in nuxt.config.ts:
export default defineNuxtConfig({
penumbra: { transition: 'circle-inverse' },
})
Or choose per call, or per PenumbraToggle:
setTheme('dark', { transition: 'fade' })
The module does not check the name. An unregistered name switches the theme instantly and does not throw.
Origin
The origin is where a reveal starts. setTheme and toggleTheme accept an Origin, which is a MouseEvent, an Element, a point in viewport pixels, or 'center'.
const { setTheme, toggleTheme } = usePenumbra()
button.addEventListener('click', (event) => toggleTheme({ origin: event })) // click position
setTheme('dark', { origin: button }) // center of an element
setTheme('dark', { origin: { x: 120, y: 40 } }) // viewport pixels
setTheme('dark', { origin: 'center' }) // middle of the screen
If you do not pass an origin, the module uses the last click, provided it happened less than a second before the call. Otherwise it uses the middle of the screen. That is what lets a foreign write, such as UColorModeButton, reveal from the button.
A click made with the keyboard (Enter or Space on a button) has no pointer position. The reveal starts from the center of the button in that case.
Duration and easing
duration is in milliseconds. It defaults to the module’s duration, which defaults to 500. easing is any CSS easing string and defaults to ease-in-out.
setTheme('dark', { duration: 800, easing: 'cubic-bezier(0.2, 0, 0, 1)' })
Both options also exist in nuxt.config.ts and as props on PenumbraToggle.
When it switches instantly
The theme always changes. The animation is skipped, and the change applies at once, when any of these is true:
document.startViewTransitiondoes not exist in the browser. See browser support.- The visitor has
prefers-reduced-motion: reduceset. It is read when the theme is changed, not watched live. durationis 0.- The effect name is not registered.
- A page navigation is running. The router flag and Nuxt’s
page:view-transition:starthook both count. See below. - The resolved theme did not change, for example switching to
systemwhile the system already matches the shown theme. - The theme is forced by color-mode (
forced).
Navigation
A theme transition never runs during a page navigation. A second view transition would cancel Nuxt’s own page transition and leave the navigation half done, so the theme change applies instantly instead. This was checked in Chromium and WebKit with experimental.viewTransition on.
Calling it again while one is running
A second change during a running transition skips the first one cleanly, and the page ends on the latest theme. There is no function that cancels a transition without starting another one.
Notes
Before it starts a new transition, @penumbra/core cancels any effect still running. Headless Chromium 159 crashed when a view transition started while the pseudo-element animation of another one was running.
Style the transition yourself
For the length of each transition, the module switches off the browser’s default cross-fade on ::view-transition-old(root) and ::view-transition-new(root), and removes that style afterwards. It also turns off CSS transitions and animations on the page for the frame of the change, so elements with their own transition do not lag behind the new theme. Do not add your own animations to those pseudo-elements for the root, or they will fight the effect.
To make your own effect, see custom transitions.