If you've ever needed to show how different parts of a system communicate, sequence diagrams are one of the clearest ways to do it. PlantUML lets you write these diagrams using plain text no dragging shapes or drawing arrows. You type simple code, and a diagram appears. But getting that code right can feel tricky at first, especially when you want to show loops, conditions, or multi-participant flows. That's exactly why having solid PlantUML sequence diagram code examples at your fingertips saves time and frustration.

This guide walks through real code examples you can copy, modify, and use today. Whether you're documenting an API flow, mapping out a user login process, or explaining a microservice architecture, you'll find patterns that fit.

What Is a PlantUML Sequence Diagram?

A PlantUML sequence diagram is a text-based diagram that shows interactions between participants over time. You define participants, send messages between them using arrows, and PlantUML renders the visual diagram. It uses the PlantUML markup language, which is straightforward enough that most developers pick it up quickly.

The basic structure looks like this:

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

That tiny block of text produces a diagram with two people exchanging messages. The arrow style changes depending on whether you use -> for a solid line or --> for a dashed response line.

How Do You Create a Basic Sequence Diagram in PlantUML?

Start with the @startuml and @enduml tags. These wrap every PlantUML diagram. Between them, you declare participants and messages. Here's a simple example of a user logging into a web application:

@startuml
actor User
participant "Web Browser" as Browser
participant "Web Server" as Server
participant "Database" as DB

User -> Browser: Enter credentials
Browser -> Server: POST /login
Server -> DB: Query user
DB --> Server: User found
Server --> Browser: 200 OK + session token
Browser --> User: Show dashboard
@enduml

Notice a few things here. The actor keyword draws a stick figure for human users. The participant keyword creates box-style lifelines for systems. You can give each participant a short alias using as, which keeps your code readable when participant names get long.

How Do You Show Loops and Conditions in PlantUML?

Real systems don't just send messages in a straight line. You often need to show retry logic, conditional branches, or repeated actions. PlantUML handles this with fragments. For a deeper look at loop syntax, see this breakdown of sequence diagram loop fragment syntax.

Here's an example showing a payment retry loop with a conditional check:

@startuml
participant Client
participant "Payment Gateway" as PG

Client -> PG: Submit payment
loop 3 times (retry on failure)
PG -> PG: Process transaction
alt payment successful
PG --> Client: 200 OK
else payment declined
PG --> Client: 402 Error
Client -> PG: Retry payment
end
end
@enduml

The loop keyword creates a repeat block. The alt and else keywords create an if/else branch. You can also use opt for optional steps that only happen under certain conditions, and par for parallel actions.

Common Fragment Keywords at a Glance

  • loop repeat a set of messages
  • alt / else / end conditional branching (if/else)
  • opt optional behavior (single condition, no else)
  • par parallel or concurrent actions
  • critical a section that must complete without interruption
  • break exit from a loop early

Understanding these UML sequence diagram symbols and their meanings helps you choose the right fragment for each situation.

How Do You Show Notes, Activation Bars, and Grouping?

Adding context to your diagram makes it more useful for teammates who read it later. PlantUML supports notes, activation rectangles, and grouping to clarify what's happening at each step.

@startuml
participant "API Client" as Client
participant "Auth Service" as Auth
participant "Resource Server" as RS

Client -> Auth: Request token (client_id, secret)
activate Auth
Auth -> Auth: Validate credentials
Auth --> Client: JWT token
deactivate Auth

note right of Auth: Token expires in 3600s

Client -> RS: GET /api/data (Bearer token)
activate RS
RS -> Auth: Verify token
Auth --> RS: Token valid
RS --> Client: 200 OK + data
deactivate RS
@enduml

activate and deactivate add the thin rectangles on a lifeline that show when a participant is actively processing. Notes attach extra information use note left of or note right of to position them.

How Do You Handle Multiple Scenarios or Alternate Flows?

Many real interactions have more than one path. Here's how to show a complete authentication flow with both success and failure paths:

@startuml
actor User
participant App
participant "OAuth Server" as OAuth

User -> App: Click "Sign In"
App -> OAuth: Authorization request
OAuth --> User: Show login page
User -> OAuth: Submit credentials

alt credentials valid
OAuth -> OAuth: Generate auth code
OAuth --> App: Redirect with code
App -> OAuth: Exchange code for token
OAuth --> App: Access + refresh tokens
App --> User: Welcome screen
else credentials invalid
OAuth --> User: Error: incorrect password
User -> OAuth: Re-enter credentials
end
@enduml

This pattern showing the happy path in the alt block and the error path in else is one of the most common structures in real-world sequence diagrams.

What Are Common Mistakes When Writing PlantUML Sequence Diagrams?

Even though PlantUML syntax is simple, a few issues come up regularly:

  • Forgetting to declare participants. If you use a name in a message without declaring it first, PlantUML will auto-create it but the order might not match what you want.
  • Mismatched arrow types. Using -> (synchronous call) when you mean --> (return/response) makes the diagram misleading.
  • Not closing fragments. Every loop, alt, opt, or par block needs a matching end. Missing one breaks the whole diagram.
  • Overcrowded diagrams. Trying to show every micro-step in one diagram makes it unreadable. Break complex flows into separate diagrams instead.
  • Ignoring activation bars. Without them, it's hard to tell when a participant is actively doing something vs. just waiting for a response.

You can explore more practical examples in this collection of PlantUML sequence diagram code examples covering additional patterns and edge cases.

How Do You Add Timers, Delays, and Destroy Messages?

Sometimes you need to show that something takes time, that a participant gets removed, or that a timeout occurs. PlantUML handles all of these:

@startuml
participant "Client" as C
participant "Cache" as Cache
participant "Origin Server" as Origin

C -> Cache: GET /resource
activate Cache

alt cache hit
Cache --> C: 200 OK (cached response)
else cache miss
Cache -> Origin: Fetch resource
...wait 200ms...
Origin --> Cache: 200 OK + data
Cache -> Cache: Store in cache
Cache --> C: 200 OK
end

deactivate Cache
@enduml

The three dots (...) with text between them create a delay indicator. If you need to show a participant being removed, use the destroy keyword for example, destroy Session would show an X at the end of that lifeline.

Can You Style PlantUML Sequence Diagrams?

Yes, PlantUML gives you control over colors, fonts, and skin parameters. A few practical styling commands:

  • skinparam sequenceArrowThickness 2 makes arrows thicker and easier to read
  • skinparam responseMessageBelowArrow true places return messages below the arrow
  • skinparam participantPadding 10 adds more spacing between lifelines
  • skinparam backgroundColor #FEFEFE sets a light background

Place these between @startuml and your first participant declaration. Styling won't fix a bad diagram structure, but it can make a good diagram much easier to read in documentation or presentations.

Where Can You Render PlantUML Diagrams?

You have several options for turning your text code into a rendered diagram:

  • PlantUML Online Server paste code and get an instant image at plantuml.com/plantuml
  • VS Code extension preview diagrams as you type with the PlantUML extension
  • IntelliJ / JetBrains IDEs built-in PlantUML plugin with live preview
  • Command line run PlantUML JAR files to generate PNG, SVG, or PDF output
  • CI/CD pipelines auto-generate diagrams from source-controlled text files during builds

Storing diagram code as text files in your repository means diagrams stay version-controlled alongside your code. When the system changes, you update a few lines of text instead of redrawing a whole diagram.

Quick Checklist for Writing PlantUML Sequence Diagrams

  • Start and end with @startuml and @enduml every diagram needs these wrapper tags
  • Declare participants at the top use aliases for long names
  • Use the right arrow style solid for calls, dashed for returns
  • Add activation bars show when participants are actively processing
  • Group related logic use loop, alt, opt, and par fragments where appropriate
  • Keep diagrams focused aim for 5-10 participants max per diagram
  • Include notes for context especially for non-obvious business rules
  • Test your code render frequently to catch syntax errors early
  • Store diagram source in version control treat it like code, not like an image

Start by taking one of the examples above, pasting it into the PlantUML online server, and modifying it to match your own system. You'll have a working diagram in under five minutes.