# How to Enable Trace Animation in Archify Diagrams

> Learn how to enable trace animation in Archify diagrams by setting meta animation trace in your diagram schema. Enhance your HTML renders with SVG trace animations. Get clear instructions now.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-07-21

---

**Set `meta.animation: "trace"` in your diagram schema to enable SVG trace animations for HTML renders.**

Archify is an open-source diagramming tool that supports lightweight trace animations for presentations and demos. By configuring a single metadata property, you can add CSS-driven flow effects to your diagrams without affecting static exports.

## Understanding Trace Animation in Archify

Trace animation creates a visual flow effect along edges and nodes using CSS keyframes. This feature is opt-in and implemented entirely within the HTML rendering pipeline.

### Core Implementation Files

The animation system spans two critical files in the `tt-a1i/archify` repository:

- **`archify/renderers/shared/cli.mjs`** – Detects the animation flag and injects the `data-animation` attribute
- **[`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)** – Provides the CSS keyframes (`archify-edge-flow`, `archify-node-pulse`) that drive the visual effect

## Configuring Trace Animation in Diagram Schemas

To activate trace animation, add the `animation` property to your diagram's `meta` object.

### Step 1 – Set the Animation Metadata

In your JSON or YAML schema, specify `meta.animation` as `"trace"`:

```json
{
  "schema_version": "1.0",
  "diagram_type": "workflow",
  "meta": {
    "title": "User Registration Flow",
    "animation": "trace"
  },
  "lanes": [{ "id": "frontend", "label": "Frontend" }],
  "nodes": [
    { "id": "login", "lane": "frontend", "label": "Login Page" },
    { "id": "signup", "lane": "frontend", "label": "Signup Page" }
  ],
  "edges": [
    { "source": "login", "target": "signup", "label": "click", "meta": { "animate": true } }
  ]
}

```

### Step 2 – Render to HTML Format

Use the CLI to generate the animated HTML output:

```bash
archify render registration.json --format=html > registration.html

```

Opening the resulting file in a browser displays the trace animation.

## How the Renderer Handles Animation Flags

According to the source code in `archify/renderers/shared/cli.mjs`, the renderer checks for `meta.animation === 'trace'` before injecting animation attributes:

```javascript
// archify/renderers/shared/cli.mjs
const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
// ...
if (meta.animation !== 'trace') return '';

```

When the condition is met, the renderer adds `data-animation="trace"` to the root `<svg>` element. The bundled template ([`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)) then activates CSS animations for elements carrying `data-animate="edge"` or `data-animate="node"` attributes.

## Accessibility and Output Format Limitations

Trace animation only applies to HTML renders. When exporting to PNG or static SVG, the animation flags are ignored and you receive a static diagram.

The CSS implementation respects `prefers-reduced-motion` media queries. Users with reduced motion preferences enabled in their operating system will see a static diagram even when trace animation is configured.

## Summary

- **Set `meta.animation: "trace"`** in your diagram schema to enable the feature
- **Render with `--format=html`** to generate animated output
- The renderer in `archify/renderers/shared/cli.mjs` injects `data-animation="trace"` when the flag is detected
- CSS keyframes in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) drive the visual flow effect
- **Respects accessibility**: Honors `prefers-reduced-motion` settings automatically
- **HTML-only**: Does not affect PNG, static SVG, or CLI text output

## Frequently Asked Questions

### What file controls the trace animation logic in Archify?

The detection and injection logic resides in `archify/renderers/shared/cli.mjs`. This file checks if `meta.animation` equals `"trace"` and conditionally adds the `data-animation` attribute to the generated SVG markup.

### Does trace animation work in static image exports?

No. Trace animation only activates when rendering to HTML format. PNG exports and static SVG files ignore the `meta.animation` property and render without motion effects.

### How can I respect user preferences for reduced motion?

Archify's CSS implementation in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) includes `prefers-reduced-motion` media queries. When users have reduced motion enabled in their system settings, the browser automatically suppresses the trace animation and displays a static diagram.

### Can I animate specific edges or nodes while leaving others static?

Yes. Individual edges and nodes support an `animate` property within their `meta` objects. When set to `true`, the renderer adds `data-animate="edge"` or `data-animate="node"` attributes, allowing selective animation while the global `meta.animation: "trace"` setting enables the overall animation system.