# Custom animations

> Write your own idle or handoff, and bundle options into presets.

Every 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`.

```ts
import { labelPulse } from 'dotquilt/animations/text';

totalLoader.animations = { idle: labelPulse() };
```

## 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.

```ts title="animations.ts"
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

```tsx
<SkeletonBlock animations={{ idle: tide({ wavelength: 160 }) }} />
<LoadingRegion animations={{ handoff: rise() }} … />
```

## 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`.
