Sequence Diagrams in VS Code: Mermaid, PlantUML, and Browser Alternatives

VS Code has no built-in sequence diagram support, but two extensions cover the space: Mermaid Preview (text-based, client-side rendering) and PlantUML (more features, needs Java). If you cannot install extensions on a locked-down work machine, a browser-based alternative handles the same diagrams without any VS Code dependency.

This guide covers all three approaches with exact setup steps and copy-paste examples. Try any diagram in our free sequence diagram tool to preview before committing to a workflow.

Option 1: Mermaid Preview Extension

Mermaid is the easiest VS Code path. No Java, no server, no external dependencies. Install the "Markdown Preview Mermaid Support" extension from the marketplace, then any Mermaid code block in a markdown file renders in the preview pane.

Setup:

1. Open Extensions (Cmd/Ctrl+Shift+X)
2. Search "Markdown Preview Mermaid Support"
3. Install the extension by bierner
4. Open any .md file with a mermaid code block
5. Cmd/Ctrl+Shift+V to open preview

Your markdown file:

# API Auth Flow

```mermaid
sequenceDiagram
    actor User
    participant App
    participant Auth

    User->>App: Login
    App->>Auth: Verify
    Auth-->>App: Token
    App-->>User: Dashboard
```

The preview pane shows the rendered diagram. Edits to the code update the preview on save. No render button needed.

For dedicated Mermaid editing (without markdown), install "Mermaid Editor" or "Mermaid Markdown Syntax Highlighting" extensions. They add syntax highlighting and error detection in .mmd files.

This is the path most developer teams pick because the same Mermaid code renders natively in GitHub and GitLab without any additional setup. Write once, view everywhere. See our complete Mermaid syntax guide for every feature.

Option 2: PlantUML Extension

PlantUML offers more diagram types than Mermaid (deployment, timing, component diagrams) but requires Java. For sequence diagrams specifically, the extra features rarely matter, but if your team already uses PlantUML elsewhere, the extension is worth having.

Setup:

1. Install Java Runtime if you do not have it (brew install --cask temurin on Mac, or download from Adoptium)
2. Install Graphviz for non-sequence diagrams (brew install graphviz on Mac)
3. Install "PlantUML" extension by jebbs from the VS Code marketplace
4. Create a .puml or .plantuml file
5. Alt+D to preview

A PlantUML sequence diagram file:

@startuml
actor User
participant "Auth Service" as Auth
User -> Auth: Login
Auth --> User: Token
@enduml

The extension renders the diagram in a side panel. You can export PNG or SVG from the preview. The extension can also use a remote PlantUML server instead of local Java, which avoids the Java install but sends your diagram code to the server.

Common issues: "Cannot find plantuml.jar" usually means Java is not installed or not in PATH. Restart VS Code after installing Java. If the preview is blank, check the OUTPUT panel for error messages — they usually point to the exact problem.

For a direct Mermaid vs PlantUML feature comparison, see our full comparison.

Sell Custom Apparel — We Handle Printing & Free Shipping

Option 3: Browser-Based (No VS Code Extension Needed)

If you cannot install VS Code extensions (locked corporate machine, Codespaces environment, remote development), a browser-based sequence diagram tool works as a parallel editor. Keep VS Code open for code, keep the diagram tool open in a browser tab, move between them as needed.

The workflow:

1. Open the browser sequence diagram tool in a tab
2. Write your diagram in Mermaid syntax with live preview
3. Export as SVG or PNG
4. Save the exported image in your project's docs folder
5. Reference it from your markdown: ![Auth Flow](./docs/auth-flow.svg)

Alternative workflow using Mermaid code directly: write the diagram in the browser tool, copy the Mermaid source, paste it into a markdown file in VS Code inside a mermaid code fence. When you push to GitHub, the diagram renders natively in the README.

This approach works for anyone. No extension install permissions required. No Java required. Works in Codespaces, on Chromebooks, on machines where IT locks down software. The diagram code lives in your repository as plain text either way.

Fast Keyboard Workflow for VS Code Users

Once you have either extension installed, the keyboard workflow for sequence diagrams becomes extremely fast:

• Cmd/Ctrl+Shift+V — Open markdown preview (for Mermaid)
• Alt+D — Preview PlantUML diagram (jebbs extension)
• Cmd/Ctrl+K V — Open preview to the side (split view)
• Cmd/Ctrl+S — Save triggers re-render in most extensions

For teams doing a lot of API documentation, split view is the killer feature. Code on one side, diagram preview on the other. Edit the text, see the diagram update. This is genuinely faster than any drag-and-drop UML tool because you never move your hands from the keyboard.

For snippets, create VS Code snippets for common diagram patterns. A snippet for "auth flow" or "crud flow" gives you a starting template that you modify for each specific use case. This cuts diagram creation from minutes to seconds for patterns you use repeatedly.

Version-controlling your diagrams alongside code means pull request reviews include diagram diffs. When the auth flow changes, the diagram and the code change in the same commit. Nobody has to wonder whether the diagram is still accurate.

Exporting Diagrams from VS Code

Both extensions support export:

Mermaid Preview: Right-click the preview pane, choose "Copy image" or use the "Save as" option if your extension supports it. For guaranteed export, use the Mermaid CLI: npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

PlantUML Extension: Right-click inside the .puml file and choose "Export Current Diagram" (or "Export Workspace Diagrams" for batch). You can configure output format in settings: PNG, SVG, or PDF.

For pipeline builds where you want diagrams generated automatically as part of documentation, both Mermaid and PlantUML have CLIs that work in CI. A GitHub Action that runs mmdc on every push ensures your exported diagrams stay in sync with the source.

If extension-based export is unreliable (it can be, especially with paths containing spaces or special characters), the browser-based tool is a fallback that always works. Copy the Mermaid code from VS Code, paste into the browser tool, click Export. No CLI configuration needed.

Frequently Asked Questions

How do I create sequence diagrams in VS Code?

Install either the Markdown Preview Mermaid Support extension (for Mermaid syntax, no extra dependencies) or the PlantUML extension by jebbs (more features, requires Java). Both render diagrams in a preview pane. Open a .md or .puml file, write your diagram code, and open the preview.

Do I need to install Java to create sequence diagrams in VS Code?

Only if you use PlantUML. The Mermaid extensions run entirely on Node.js and require no Java. For the simplest setup, use Mermaid. Java is only needed for PlantUML and Graphviz-based diagrams.

Can I export sequence diagrams from VS Code as PNG or SVG?

Yes. Both Mermaid and PlantUML extensions support export. Mermaid can export through the preview pane context menu or the Mermaid CLI. PlantUML exports through right-click in the .puml file. For guaranteed export, a browser-based tool works as a fallback.

Which is better for VS Code: Mermaid or PlantUML?

For sequence diagrams specifically, Mermaid is easier (no Java, native GitHub rendering). PlantUML is better if you need diagram types Mermaid does not support (deployment, timing, component) or if your team already uses PlantUML elsewhere.