Custom animations
Copy pageEvery loader has two animations: an idle that plays while it waits, and a handoff that plays when the content arrives. You can swap either for a built-in alternative, or write your own with defineAnimation.
import { labelPulse } from 'dotquilt/animations/text';
totalLoader.animations = { idle: labelPulse() };Write your own
Section titled “Write your own”An animation draws with commands, not with the DOM: an idle places marks with dot(), and a handoff can also move your content with reveal(). Dotquilt owns the timing, the restrictions and the cleanup, so a custom animation still pauses, respects reduced motion and stops after four seconds.
Each dot() takes a centre (x, y), a radius (size), an opacity and a tone (base, or accent for the glow colour). The loader’s mark decides the shape. An optional angle, in radians clockwise, turns squares and dashes about their centre; dots ignore it.
import { defineAnimation, definePreset } from 'dotquilt/animations';import type { SkeletonBlock } from 'dotquilt/skeleton';
/** * An idle for skeletons: a slow tide of brighter marks rolling across each * shape. `frame` draws one moment; `still` draws the resting picture used for * reduced motion, a pause and server rendering. */export const tide = defineAnimation({ contractVersion: 1, id: 'example/tide', family: 'skeleton', phase: 'idle', options: { // Options are parsed once and frozen; reject or default anything odd here. parse: (value: Readonly<Partial<{ wavelength: number }>>) => ({ wavelength: Math.max(40, value.wavelength ?? 120), }), }, frame({ surface, frame, dot }, { wavelength }) { for (const shape of surface.input.shapes) for (let x = shape.x + 4.5; x < shape.x + shape.width; x += 9) for (let y = shape.y + 4.5; y < shape.y + shape.height; y += 9) { const wave = Math.sin((x - frame.timeMs / 12) / (wavelength / 6.28)); dot({ x, y, size: 2.2, opacity: 0.37 + 0.2 * wave, tone: 'base' }); } }, still({ surface, dot }) { for (const shape of surface.input.shapes) for (let x = shape.x + 4.5; x < shape.x + shape.width; x += 9) for (let y = shape.y + 4.5; y < shape.y + shape.height; y += 9) dot({ x, y, size: 2.2, opacity: 0.37, tone: 'base' }); },});
/** * A handoff for regions: content rises 8 px while it fades in. `duration` * says how long it takes; `frame` is called with the progress, from 0 to 1. */export const rise = defineAnimation({ contractVersion: 1, id: 'example/rise', family: 'region', phase: 'handoff', options: { parse: (value: Readonly<Partial<{ distance: number }>>) => ({ distance: value.distance ?? 8, }), }, duration: () => 700, prepare: () => undefined, frame({ frame, reveal }, { distance }) { reveal({ opacity: frame.progress, translateY: (1 - frame.progress) * distance, }); },});
/** A preset bundles options you reuse: here, a calmer skeleton. */export const calm = definePreset({ kind: 'skeleton', speed: 0.6, animations: { idle: tide({ wavelength: 200 }) },});
const block = document.querySelector<SkeletonBlock>('dotquilt-skeleton-block');if (block) block.preset = calm;| Part | Idle | Handoff |
|---|---|---|
family |
skeleton, text, chart or table |
region, skeleton, text, chart or table |
options.parse |
turns the options you pass into frozen, valid values | the same |
frame |
draws one moment, given frame.timeMs |
draws one moment, given frame.progress from 0 to 1 |
still |
the resting picture for reduced motion and pauses | |
duration, prepare |
how long it takes, and any setup it needs once |
Use it
Section titled “Use it”<SkeletonBlock animations={{ idle: tide({ wavelength: 160 }) }} /><LoadingRegion animations={{ handoff: rise() }} … />Presets
Section titled “Presets”definePreset bundles options you reuse, such as a speed and animations, and checks them once. Give it to any loader of the same kind as preset.