# How to Use Optional Animation Modes in diagram-design: A Complete Guide

> Master optional animation modes in diagram-design. Learn to control animation with the export-diagram command and animation flags like none, linear, ease-in, ease-out, and ease-in-out.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Use the `--animation-mode` flag (or `-a` short form) on the `export-diagram` command to control animation behavior, with supported modes including `none`, `linear`, `ease-in`, `ease-out`, and `ease-in-out`.**

The **diagram-design** repository by cathrynlavery provides CLI and programmatic interfaces for exporting diagrams with optional animation modes. These modes control how diagram elements move during export, enabling everything from static renders to smooth motion graphics. This guide covers the available animation modes, their implementation, and practical usage examples based on the source code.

## Supported Animation Modes in diagram-design

The diagram-design library implements five distinct animation modes. Each mode applies a different **easing function** to control element motion:

| Mode | Description |
|------|-------------|
| `none` | No animation—exports a static image (default behavior) |
| `linear` | Elements move at constant speed from start to end positions |
| `ease-in` | Animation starts slowly and accelerates toward the end |
| `ease-out` | Animation starts quickly and decelerates toward the end |
| `ease-in-out` | Combines ease-in and ease-out for smooth start and finish |

When omitted, the system defaults to `none`, producing static output. The mode selection directly influences how the rendering engine constructs frame sequences during export.

## CLI Usage: The --animation-mode Flag

The `export-diagram` command exposes animation control through the **`--animation-mode`** flag. This is documented in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) and implemented in the CLI parser.

### Basic Static Export (Default)

```bash
export-diagram my-diagram.mmd --output diagram.png

```

No animation flag required—the default `none` mode applies automatically.

### Linear Animation with Custom Duration

```bash
export-diagram my-diagram.mmd -a linear --duration 5 --output diagram.gif

```

The `-a` short form accepts `linear` for constant-speed motion across a 5-second loop.

### Ease-in-out with Frame Rate Control

```bash
export-diagram my-diagram.mmd --animation-mode ease-in-out \
    --frame-rate 30 --output animated-diagram.mp4

```

Full flag name `--animation-mode` used here with `ease-in-out` for professional smooth motion at 30fps.

## Programmatic API Usage

For JavaScript/TypeScript projects, the **`exportDiagram`** function from `@diagram-design/core` accepts an `animationMode` parameter:

```javascript
import { exportDiagram } from '@diagram-design/core';

await exportDiagram({
  source: 'graph.mmd',
  output: 'graph.gif',
  animationMode: 'ease-out',   // optional, defaults to 'none'
  duration: 4,                 // seconds
  frameRate: 24,
});

```

The programmatic interface mirrors CLI behavior: omit `animationMode` or set explicitly to `'none'` for static output.

## Where Animation Modes Are Implemented

Understanding the source structure helps when customizing or debugging animation behavior:

- **[`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)** — Documents the `--animation-mode` flag syntax and supported values
- **[`prompts/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/export-diagram.md)** — Prompt template generating command snippets with animation options
- **[`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py)** — Validation script testing motion-related options including mode parsing

The CLI passes parsed flags to the diagram-design SDK's animation utilities, which map mode strings to easing function implementations in the rendering pipeline.

## Animation Mode Selection Guidelines

Choose your mode based on export purpose:

- **Documentation/static sites** — Use `none` (default) for crisp, predictable images
- **Technical tutorials** — `linear` provides consistent, easy-to-follow motion
- **Marketing/presentations** — `ease-in-out` delivers polished, professional aesthetics
- **Attention-directing** — `ease-out` draws focus with quick-start-then-settle behavior

## Summary

- **diagram-design** supports five animation modes: `none`, `linear`, `ease-in`, `ease-out`, and `ease-in-out`
- Control via `--animation-mode` flag or `-a` short form in CLI; `animationMode` parameter in JavaScript API
- Default mode is `none`, producing static output when no flag is specified
- Mode selection determines easing function applied by the rendering engine
- Source documentation in [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) and validation in [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py)

## Frequently Asked Questions

### What happens if I don't specify an animation mode?

The system defaults to `none`. Your diagram exports as a static image without motion, regardless of output format. This ensures predictable, fast exports when animation isn't required.

### Can I combine animation modes in a single export?

No. Each export accepts exactly one animation mode. The rendering engine applies a single easing function across all animated elements. For complex multi-phase animations, export separate sequences and composite externally.

### Which output formats support animation?

GIF and MP4 formats preserve animation. PNG and static image formats automatically disable animation regardless of mode selection. The CLI warns when mode conflicts with output format, falling back to `none` for incompatible combinations.

### How does the frame rate interact with animation mode?

Frame rate (`--frame-rate` or `frameRate` option) determines sampling density. Higher rates (30fps+) produce smoother motion, especially noticeable with `ease-in` and `ease-out` modes where acceleration changes are subtle. `linear` mode tolerates lower rates due to constant velocity.