Skip to content
nuxt-penumbra
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.startViewTransition does not exist in the browser. See browser support.
  • The visitor has prefers-reduced-motion: reduce set. It is read when the theme is changed, not watched live.
  • duration is 0.
  • The effect name is not registered.
  • A page navigation is running. The router flag and Nuxt’s page:view-transition:start hook both count. See below.
  • The resolved theme did not change, for example switching to system while the system already matches the shown theme.
  • The theme is forced by color-mode (forced).

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.

Was this page helpful?