Skip to content
Astro Eclipse
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.startViewTransition does not exist in the browser. See browser support.
  • The visitor has prefers-reduced-motion: reduce set.
  • duration is 0.
  • The effect name is not registered. This does not throw.
  • Astro’s ClientRouter is in the middle of a navigation. See ClientRouter.
  • The resolved theme did not change, for example switching from system to light while 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.

Was this page helpful?