Custom transitions
Register your own effect with definePenumbraTransition, with a worked example.
An effect is a name plus keyframes for the old snapshot, the new snapshot, or both. definePenumbraTransition registers it, and from then on the name works in nuxt.config.ts, in setTheme and on PenumbraToggle. It is an alias of defineTransition from @penumbra/core and is auto-imported.
function definePenumbraTransition(name: string, definition: TransitionDefinition): TransitionDefinition
interface TransitionDefinition {
old?: (context: TransitionContext) => Keyframe[]
new?: (context: TransitionContext) => Keyframe[]
top?: 'old' | 'new' // which snapshot is drawn above the other, default 'new'
}
interface TransitionContext {
origin: { x: number; y: number } // viewport pixels
direction: 'up' | 'down' | 'left' | 'right' // default 'right'
width: number // viewport width
height: number // viewport height
}
old animates ::view-transition-old(root) and new animates ::view-transition-new(root). Return normal Keyframe[], the same array you would give element.animate(). The module applies the duration and easing, so leave them out of the keyframes.
Example: a rectangle that grows from the origin
The new theme appears in a rectangle that starts as a point at the origin and grows to the full viewport. clip-path: inset(top right bottom left) does that: each value cuts that many pixels from one edge.
export default defineNuxtPlugin(() => {
definePenumbraTransition('grow', {
new: ({ origin, width, height }) => [
{
clipPath: `inset(${origin.y}px ${width - origin.x}px ${height - origin.y}px ${origin.x}px)`,
},
{ clipPath: 'inset(0px 0px 0px 0px)' },
],
})
})
A plugin with the .client.ts suffix runs once in the browser at startup, before any toggle is clicked. Then use the name:
<PenumbraToggle transition="grow" />
setTheme('dark', { transition: 'grow', origin: event })
To make it the default, set transition: 'grow' in the module options. The module does not check the name at build time, so a typo falls back to an instant switch.
Example: reveal from the top
An effect does not have to use the origin:
definePenumbraTransition('curtain-down', {
new: () => [{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
})
Pick a name that is not already built in, since registering an existing name replaces it.
Which snapshot goes on top
By default the new snapshot is drawn above the old one, so an effect on new reveals it. To reveal the new theme by removing the old one, put the old snapshot on top and animate it away. circle-inverse works this way:
definePenumbraTransition('shrink', {
top: 'old',
old: ({ origin, width, height }) => [
{ clipPath: `circle(${Math.hypot(width, height)}px at ${origin.x}px ${origin.y}px)` },
{ clipPath: `circle(0px at ${origin.x}px ${origin.y}px)` },
],
})
Math.hypot(width, height) is a radius that covers the viewport from any point inside it.
Rules
- Register it in code that runs in the browser before the first change. A
.client.tsplugin does that. - Registering an existing name replaces it, built-in names included.
- Keyframes run only when the transition runs. In the cases where the theme switches instantly your function is not called.
- Keep keyframes to properties the browser can animate on the root snapshot, such as
clip-path,opacityandtransform. Other properties have not been checked. - The types are not exported from the package entry. Copy the shapes above if you need to annotate your own code. The auto-imported function is typed.
Related: API reference, transitions.