# SVG animation

Revealer can inline an SVG file into a slide and reveal or transform its
elements step by step, by referencing their `id`. Each step is tied to a
reveal.js fragment, so it advances with the arrow keys and reverts when you step
back.

## Inlining an SVG

Add a `> svg:` command to a slide, with a path relative to the presentation
folder:

```
=== A diagram
> svg: Media/Animated/scheme.svg

Some explanatory text.
```

The SVG is embedded directly in the slide (not via `<img>`), which is what makes
its inner elements addressable for animation.

`> svg:` also accepts a `.pdf` path: the PDF is converted to SVG on the fly
and cached (see the [figures pipeline](figures.md)).

## Hiding elements up front

`> hide:` sets the initial state of elements without touching the SVG file:
each listed `id` gets `opacity="0"` when the SVG is inlined, ready to be
revealed by an `> animate:` step. Ids are comma-separated (the leading `#`
is optional) and the directive is repeatable:

```
=== Animated SVG
> svg: Media/Animated/demo.svg
> hide: #dot, #arrow
> animate: #dot opacity:1
> animate: #arrow opacity:1
```

This is handy for figures exported from tools that make pre-hiding elements
awkward — the source SVG stays fully visible when opened on its own.

## Animation steps

Each `> animate:` line defines one step. Its syntax is:

```
> animate: <selector>[,<selector2>] <attr>:<value>[; <attr2>:<value2>] [@ <duration>]
```

* **selector** — one or more CSS selectors (typically `#id`) targeting elements
  inside the SVG. Several selectors can be comma-separated (spaces after the
  commas are fine): `> animate: #dot, #arrow opacity:1`.
* **attributes** — one or more `name:value` pairs, separated by `;`. They are
  applied as SVG attributes (`opacity`, `fill`, `transform`, …).
* **duration** *(optional)* — the transition time for this step, written after
  an `@` (e.g. `@ 1s`, `@ 300ms`). Defaults to the global `> svgDuration:`
  setting (`0.5s`).

### Example

```
=== Animated SVG
> svg: Media/Animated/demo.svg
> animate: #box fill:#0F4C75
> animate: #dot opacity:1; fill:#c0392b @ 1s
> animate: #arrow opacity:1 @ 300ms

Reveal SVG elements step by step by referencing their <code>id</code>.
```

Here, advancing the slide first colours `#box`, then fades in `#dot` while
recolouring it over one second, then reveals `#arrow` quickly. Stepping back
restores each element to its original state.

## Tips

* Give meaningful `id`s to the elements you want to animate in your SVG editor
  (Inkscape: *Object Properties → ID*).
* Set the SVG's initial state (e.g. `opacity="0"`) directly in the file, or
  keep the file untouched and use `> hide:`; the animation moves elements
  *from* that state.
* `transform` animates too — e.g. `transform:translate(100,0)` or
  `transform:scale(1.5)`. Note that SVG transforms are about the
  **user-space origin**, not the element: to scale an element about its own
  centre, wrap it in a `<g transform="translate(x,y)">` whose inner geometry
  is drawn centred on `0,0`, and animate the inner element.
* Arrowheads and other `<marker>`s scale with the stroke width by default
  (`markerUnits="strokeWidth"`), so a thick arrow gets an oversized head —
  set `markerUnits="userSpaceOnUse"` on the marker to keep it constant.
* The default global duration can be changed once for the whole presentation
  with `> svgDuration: 0.8s` in the settings.