MermanDraw
Open Editor

Mermaid guide

ZenUML in Mermaid: Code-Style Sequence Diagrams with Nested Calls

ZenUML is an alternative sequence-diagram syntax that Mermaid can render through a plugin. Instead of one arrow per line, you write something that looks like code: a call with braces, nested calls inside, and return lines. The renderer turns the nesting into activation bars and reply arrows.

It suits developers who think in method calls. The classic sequenceDiagram is still the safer choice for GitHub and most renderers, which do not load the ZenUML plugin.

  • DDD interaction modelling
  • method-call hierarchies
  • service collaboration docs
  • OO sequence flows

Example

ZenUML needs the separate ZenUML plugin; the preview is not available here. The code is still copy-ready. 

zenuml
    title Order Service
    @Actor User
    @Boundary OrderUI
    @Control OrderService
    @Entity OrderDB

    User -> OrderUI.placeOrder(item) {
      OrderUI -> OrderService.createOrder(item) {
        OrderService -> OrderDB.save(order)
        return orderId
      }
      return confirmation
    }
Open in editor → Cheatsheet →

Syntax

Participants and calls

zenuml
    title Place order
    @Actor Customer
    @Boundary Checkout
    @Control OrderService
    @Entity OrderRepo

    Customer -> Checkout.submit(cart) {
      Checkout -> OrderService.create(cart) {
        OrderService -> OrderRepo.save(order)
        return orderId
      }
      return confirmation
    }

ZenUML needs the separate ZenUML plugin; the preview is not available here. The code is still copy-ready.

Annotations pick the participant icon. A call is Caller -> Callee.method(args) { ... }; the braces hold whatever happens during that call.

Try this snippet →

Loops and conditions

zenuml
    @Actor User
    User -> Cart.checkout() {
      if (cart.isEmpty) {
        return error
      } else {
        while (item in cart) {
          Cart -> Inventory.reserve(item)
        }
        return ok
      }
    }

ZenUML needs the separate ZenUML plugin; the preview is not available here. The code is still copy-ready.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • Expecting ZenUML to render on GitHub.

    Fix: GitHub does not load the ZenUML plugin. Use sequenceDiagram, or export a PNG from MermanDraw and embed the image.

  • Unbalanced braces.

    Fix: Each { needs a }. Indent consistently; the parser error points at the line where the mismatch is detected, which is often the last line.

FAQ

Should I use ZenUML or sequenceDiagram?

Use sequenceDiagram for anything that must render in GitHub, GitLab, Notion plugins, or docs generators. Use ZenUML when you control the renderer and prefer code-like nesting.

Can I convert between them?

Not automatically. Both are text, though, so an AI assistant can translate one to the other reliably if you give it both examples.