If you've ever stared at a blank screen trying to map out how different parts of your system talk to each other, you know the pain. Sequence diagrams solve that problem visually and PlantUML lets you build them with plain text instead of dragging boxes around in a tool. Learning how to write PlantUML code for sequence diagrams means you can create, version-control, and update diagrams as fast as you type. No mouse-clicking, no licensing fees, no exporting headaches.

What is a PlantUML sequence diagram?

A PlantUML sequence diagram is a text-based diagram that shows how objects or actors exchange messages over time. You write short lines of code, and PlantUML renders them into a visual flow. The left-to-right layout shows which participant sends a message and which one receives it. Time flows downward on the diagram, so the order of your code lines matches the order of events in the image.

This matters because sequence diagrams are one of the most common UML diagram types used in software design, API documentation, and technical communication. When your diagram lives as code, you can store it in Git alongside your source files, diff changes between versions, and regenerate images in any CI pipeline.

How do you set up a basic PlantUML sequence diagram?

Every PlantUML sequence diagram starts and ends with a pair of tags. Inside those tags, you declare participants and define messages between them. Here is the minimum code you need:

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi back
@enduml

The @startuml and @enduml tags tell the renderer where your diagram begins and ends. The arrow syntax defines the message. A single arrow -> draws a solid line (a synchronous call), and --> draws a dashed line (a return or response). The text after the colon becomes the message label.

You do not need to explicitly declare participants in a simple diagram PlantUML creates them automatically when you reference them. But for larger diagrams, declaring participants at the top helps you control their display order.

What arrow types and message styles can you use?

PlantUML supports several arrow styles that represent different kinds of communication:

  • -> Solid arrow synchronous message or request
  • ->> Open arrow asynchronous message
  • --> Dashed arrow return or response message
  • ->x Solid arrow with an X lost message (never received)
  • o-> Arrow starting with a dot creation message

You can also add notes to the side or over a participant using the note left of, note right of, or note over keywords. These are useful for explaining logic that is not obvious from the message flow alone.

How do you show loops, conditions, and groups?

Real systems do not just send messages in a straight line. You often need to show repeated actions, conditional branches, or error handling. PlantUML uses grouping keywords for this:

  • loop repeats a block of messages (like a polling cycle or retry logic)
  • alt / else shows conditional branching (like if/else logic)
  • opt shows an optional block that only executes under certain conditions
  • par shows parallel execution of messages
  • break shows an interruption in the normal flow

Each group keyword opens a block that you close with the end keyword. You can also add a label after the keyword to describe what the group represents.

alt successful response
  Server -> Client: 200 OK
else error
  Server -> Client: 500 Internal Server Error
end

Nesting these groups is allowed and common. A loop might contain an alt block, for example, to show a retry mechanism that checks for success or failure on each attempt.

How do you customize participant appearance and ordering?

By default, PlantUML displays participants in the order they first appear in your code. If you want to reorder them or change how they look, you can use declaration keywords:

  • actor renders a stick-figure icon (good for users or external systems)
  • participant renders a standard rectangular box
  • database renders a cylinder shape (good for data stores)
  • queue renders a queue-style box
  • collections renders a stacked box style

You can also give a participant an alias: actor "Admin User" as Admin. This lets you use the short alias Admin in your message lines while the diagram displays the full label.

If you need to change the display order without rewriting your messages, the order keyword works: participant B before A.

How do you show activation bars and lifelines?

Activation bars (the thin rectangles on a lifeline that show when a participant is actively processing) are added with the activate and deactivate keywords.

Client -> Server: Request
activate Server
Server -> Database: Query
Database --> Server: Results
Server --> Client: Response
deactivate Server

Without activation bars, a busy diagram can look flat and hard to read. They help you see which participants are "doing work" at each step. You can nest activations too if Server calls Database while Server is already activated, Database gets its own inner activation bar.

A shortcut: using ++ after the arrow target activates that participant, and -- deactivates it. For example, Client -> Server++: Request is equivalent to writing a separate activate Server line.

How do you add titles, headers, footers, and styling?

PlantUML gives you a few metadata commands to make diagrams more informative:

  • title My Diagram Title adds a title at the top
  • header Page 1 adds a header
  • footer Confidential adds a footer
  • legend / end legend adds a legend block

For styling, you can change colors with skinparam commands or use spritemap for custom icons. Keep in mind that most teams using PlantUML prefer clean, minimal diagrams heavy styling can distract from the actual message flow.

If you need other diagram types alongside your sequence diagram, our class diagram syntax examples cover another commonly used UML type in PlantUML.

What are the most common mistakes when writing PlantUML sequence diagrams?

After working with PlantUML across many projects, a few errors come up repeatedly:

  • Forgetting to close groups. Every alt, loop, opt, or par block needs a matching end. Missing one causes a render error that can be hard to trace in a long diagram.
  • Mismatched arrow types. Using -> where you mean --> changes the meaning of your diagram. Solid arrows imply a call; dashed arrows imply a return.
  • Overcrowding a single diagram. If your sequence diagram has 15 participants and 80 messages, it becomes unreadable. Split it into smaller, focused diagrams.
  • No participant ordering. Letting PlantUML auto-order participants sometimes puts related systems far apart. Declare them explicitly to control the layout.
  • Ignoring aliases. Long participant names like "PaymentGatewayService" make message lines hard to read. Use aliases to keep your code clean.

Can you generate sequence diagrams from a tool instead of hand-writing code?

Yes. If you want to skip writing raw syntax, there is a UML diagram script generator tool that lets you describe your diagram in plain language and outputs valid PlantUML code. This can speed up the first draft, though most developers still hand-tune the output for accuracy.

What does a full practical example look like?

Here is a realistic example showing a user logging in through a web application that checks credentials against a database:

@startuml
title User Login Flow

actor User as U
participant "Web App" as Web
participant "Auth Service" as Auth
database "User DB" as DB

U -> Web: Enter credentials
activate Web
Web -> Auth: POST /login
activate Auth
Auth -> DB: SELECT user WHERE email = ?
activate DB
DB --> Auth: User record
deactivate DB

alt valid credentials
  Auth --> Web: 200 + JWT token
  Web --> U: Show dashboard
else invalid credentials
  Auth --> Web: 401 Unauthorized
  Web --> U: Show error message
end

deactivate Auth
deactivate Web
@enduml

This example uses actors, participants, a database, activation bars, and an alt/else group all the core building blocks covered above. For a broader reference, keep the full PlantUML sequence diagram syntax guide handy while you write your own.

Where can you render and preview your PlantUML code?

You have several options for rendering PlantUML:

  • PlantUML Online Server paste your code and get an instant image. Good for quick testing.
  • VS Code extensions the PlantUML extension gives you live preview inside your editor.
  • IntelliJ IDEA plugin similar live preview for JetBrains users.
  • Command-line JAR download the PlantUML JAR file and render diagrams from your terminal or CI pipeline.
  • Markdown integrations many documentation platforms (Confluence, MkDocs, Notion with plugins) can render PlantUML blocks directly.

Quick checklist before you ship your diagram

  • Every @startuml has a matching @enduml
  • All group blocks (alt, loop, opt, par, break) are closed with end
  • Arrow types match the intended message style (solid for calls, dashed for returns)
  • Participants are declared in the order you want them displayed
  • Activation bars are balanced every activate has a deactivate
  • Aliases are used for long participant names
  • The diagram has a title
  • The diagram renders without errors on the PlantUML online server
  • The diagram is small enough to read on a single screen (split it if not)