Mermaid to GIF: How to Turn a Diagram Into Something That Moves
Short answer: Mermaid does not export GIF and does not animate. Getting from Mermaid to GIF means rendering the diagram outside Mermaid and assembling frames yourself, running one of the community scripts that automates that, or generating an animated version from the same definition with a tool built for it. The choice depends entirely on whether you want a moving picture or a diagram that builds in the order you explain it.
Those are not the same request, and most of the tooling confuses them.
Why doesn't Mermaid export a GIF?
Mermaid renders to SVG in a browser. That is its whole job. The rendered output has no timeline, no keyframes, and no notion of a step happening after another step — the arrows in a sequence diagram are drawn in source order, all at once, in a single paint.
The request for animation is old and well documented. The Mermaid repository has carried open issues asking for animated diagrams and for PowerPoint and Google Slides export for years, and community workarounds have filled the gap: scripts that re-render a diagram repeatedly with more nodes each time, hand-rolled CSS hacks against the rendered SVG, and small CLI tools that stitch the resulting PNGs into a GIF.
They all work. They all share the same shape: render N times, collect N images, encode. Understanding that shape is what lets you judge the options.
What are the ways to get from Mermaid to an animated GIF?
The frame-stitching approach
Take your Mermaid definition. Produce several versions of it, each revealing one more node or message than the last. Render each one to PNG with the Mermaid CLI. Feed the PNGs to an encoder such as ImageMagick or ffmpeg with a frame delay.
This is what the community scripts automate, and it is genuinely the most controllable route: you decide exactly what each frame contains.
Two things bite. First, Mermaid re-lays out the graph every render, so a diagram that gains a node between frames can shift its entire layout, and the "animation" becomes a jitter. You avoid it by rendering the full diagram every time and hiding the not-yet-revealed elements rather than omitting them. Second, GIF is limited to 256 colours, and diagram text at small sizes dithers badly. Export larger than you need.
CSS animation on the rendered SVG
Mermaid emits SVG with reasonably predictable class names, so you can attach CSS animations to nodes and edges after rendering. This is the route behind most of the "terrible hacks" blog posts, and it produces genuinely good results in a browser.
It does not produce a file. A CSS-animated SVG plays where a browser plays it, which rules out PowerPoint, Keynote, and most of the places people actually need the diagram. You are back to screen-recording it, which is the frame-stitching route with extra steps.
A tool that generates the animation
The third route skips the frames entirely: read the Mermaid definition, understand the structure, and produce an animation from it. FluxDiagram's Mermaid converter takes a Mermaid or PlantUML definition — flowchart, sequence, class, Gantt or pie — extracts the nodes and edges, and generates an animated version that builds the diagram in the flow direction your source already declares. Export as GIF for a loop, or MP4 and WebM when you want controlled playback.
The tradeoff is honest: you get less frame-level control than a script gives you, and you get a result in seconds rather than an afternoon.
Which approach fits which job?
| Approach | Setup cost | Output | Layout stability | Embeds in slides | Best for | |---|---|---|---|---|---| | Frame stitching with CLI + ffmpeg | High, scripted | GIF or MP4 | Poor unless you hide rather than omit | Yes | Repeatable pipelines in CI | | CSS on rendered SVG | Medium | Browser only | Good | No | Docs sites and web pages | | Screen recording a live editor | Low | GIF or MP4 | Good | Yes | A one-off, at cursor-visible quality | | Generating from the definition | Low | GIF, MP4, WebM | Good | Yes | Slides you have to narrate |
GIF, MP4, or WebM — which should you actually export?
Ask for a GIF and you will usually get one, but it is rarely the right container.
GIF loops automatically, plays everywhere, and needs no controls. It is capped at 256 colours and file sizes climb fast, so a 20-second diagram build is a heavy file that looks worse than a 3-second one. Good for a README badge or a loop running behind you while you talk.
MP4 gives you full colour, small files, and playback control. On a slide, control matters more than people expect: you want the build to start when you press the key, not when the slide appears, and you want it to hold on the final frame rather than restarting behind your explanation.
WebM is the web equivalent, useful for a docs site or a landing page where you want transparency or a smaller payload.
The rule of thumb: GIF for a loop, MP4 for a presentation, WebM for the web.
Does an animated GIF actually help?
Not always, and it is worth being blunt because "animate the diagram" is often the wrong fix.
A looping GIF of a flowchart drawing itself over and over, behind a speaker, is decoration. It attracts the eye repeatedly and tells the audience nothing new on the second loop.
What helps is sequence tied to narration: the diagram appears in the order you explain it, so at every moment the only thing visible is the thing you are talking about. That is why the frame-stitching scripts exist, and it is the actual reason to want animation from a Mermaid diagram at all. We covered the underlying case at length in turning Mermaid diagrams into animated presentation visuals, and the format-side decisions in Mermaid to PowerPoint.
If the diagram is small enough to read at a glance, skip the animation. Export an SVG and move on.
FAQ
Can the Mermaid CLI export a GIF directly?
No. `mmdc` outputs SVG, PNG, and PDF. Anything animated requires rendering multiple stills and encoding them yourself, or a separate tool.
How do I stop the diagram jumping between frames?
Render the complete diagram in every frame and hide the elements you have not revealed yet, rather than deleting them from the definition. Mermaid recalculates layout from whatever nodes exist, so removing a node moves everything else.
Will an animated GIF play inside PowerPoint and Google Slides?
Yes. Both treat a GIF as an image and loop it automatically in presentation mode, though not always in edit view. For a build you want to trigger and hold, insert an MP4 as media instead, which gives you a play control and stops it looping.
Try it with your own definition
If you have a Mermaid diagram that needs to move, start from the source rather than the screenshot.
Paste your Mermaid code into the converter.
FluxDiagram generates animated diagrams you embed into the deck you already have, in PowerPoint, Google Slides or Keynote.