Transitions
The built-in effects, and how to set the origin, 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 Astro Eclipse animates the two snapshots with the Web Animations API. The theme itself 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. |
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 centre line, 'up' and 'down' from a horizontal one.
setTheme('dark', { transition: 'wipe', direction: 'down' })
To make your own effect, see custom transitions.
Choose an effect
Set the default for the whole site in the config:
eclipse({ transition: 'circle-inverse' })
Or choose per call:
import { setTheme } from 'astro-eclipse/client'
setTheme('dark', { transition: 'fade' })
Origin
The origin is where a reveal starts. Pass whichever form is handy:
import { setTheme, toggleTheme } from 'astro-eclipse/client'
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, also the default
A click made with the keyboard (Enter or Space on a button) has no pointer position. Astro Eclipse reveals from the center of the button in that case.
Duration and easing
duration is in milliseconds. It defaults to the config’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)' })
The config accepts duration as well. There is no config option for easing.
When it switches instantly
The theme always changes. The animation is skipped, and the change is applied 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. durationis 0.- The effect name is not registered. This does not throw.
- Astro’s
ClientRouteris in the middle of a navigation. See ClientRouter. - The resolved theme did not change, for example switching from
systemtolightwhile the system is already light.
Reduced motion is read when setTheme is called, not watched live.
Calling it again while one is running
A second setTheme during a running transition skips the first one. The first animation is cut short, and the page ends on the theme of the latest call. There is no function that cancels a transition without starting another one.
Style the transition yourself
Astro Eclipse switches off the browser’s default cross-fade for ::view-transition-old(root) and ::view-transition-new(root) for the length of each transition and removes that style afterwards. Do not add your own animations on those pseudo-elements for the root, or they will fight the effect.
Related: accessibility, client API.