Create Any Diagram Easily with PlantUML

If you've ever tried to draw a sequence diagram or a class diagram by dragging boxes and arrows around in a GUI tool, you know how tedious it gets — especially when you need to make a small change and end up nudging fifteen shapes to make room. PlantUML solves this by letting you write diagrams as plain text, the same way you'd write code.

You describe what the diagram should contain, and PlantUML handles the layout. The result is version-controllable, easy to review in a pull request, and fast to update.

In this post, we'll cover:

1. What PlantUML is and how to try it in seconds
2. Simple examples of the most useful diagram types
3. A few tips for keeping diagrams clean

What Is PlantUML?

PlantUML is an open-source tool that turns simple text descriptions into diagrams — UML diagrams (sequence, class, use case, activity, component, state) as well as non-UML ones like ER diagrams, Gantt charts, and mind maps.

Every diagram follows the same basic shape:

@startuml
... diagram content ...
@enduml

You can render it:

• Online, using the PlantUML Web Server — paste your text, get an image instantly, no install needed.
• Locally, via a Java jar file, a VS Code extension ("PlantUML" by jebbs), or plugins for IntelliJ, Confluence, and most static site generators (Jekyll, Hugo, Docusaurus all support it).

That's it — no drag-and-drop, no proprietary file format.

Example 1: Sequence Diagram

Sequence diagrams show how objects or services talk to each other over time. This is probably the diagram type people reach for most often when documenting an API flow.

@startuml
actor User
participant "Web App" as App
participant "Auth Service" as Auth
participant "Database" as DB

User -> App: Click "Login"
App -> Auth: Validate credentials
Auth -> DB: Check user record
DB --> Auth: User found
Auth --> App: Return auth token
App --> User: Show dashboard
@enduml

That's six lines of actual content, and it produces a complete, readable diagram with an actor, three participants, and the full message flow — arrows, labels, and all.

Tip: Use -> for a call and --> for a return/response. It makes the diagram easy to scan.

Example 2: Class Diagram

Useful for documenting your data model or object structure.

@startuml
class Order {
  -id: int
  -status: String
  +calculateTotal(): double
  +cancel(): void
}

class Customer {
  -id: int
  -name: String
  -email: String
}

class Product {
  -sku: String
  -price: double
}

Customer "1" -- "many" Order : places
Order "many" -- "many" Product : contains
@enduml

Notice how relationships and multiplicity ("1", "many") are just written inline — no separate connector tool required.

Example 3: Use Case Diagram

Great for capturing requirements at a glance, before you get into implementation detail.

@startuml
left to right direction
actor Customer
actor Admin

rectangle "Online Store" {
  Customer --> (Browse Products)
  Customer --> (Place Order)
  Customer --> (Track Shipment)
  Admin --> (Manage Inventory)
  Admin --> (Process Refunds)
}
@enduml

left to right direction is a small but handy setting — it keeps use case diagrams from stretching too tall.

Example 4: Activity Diagram (Flowchart)

For documenting a process or decision flow.

@startuml
start
:Receive order;
if (In stock?) then (yes)
  :Charge payment;
  :Ship order;
else (no)
  :Notify customer;
  :Cancel order;
endif
stop
@enduml

This reads almost like pseudocode, which is exactly why it's so quick to write and to update later.

Example 5: Entity-Relationship (ER) Diagram

Handy for database schemas.

@startuml
entity Customer {
  * id : int
  --
  name : varchar
  email : varchar
}

entity Order {
  * id : int
  --
  customer_id : int
  order_date : date
}

Customer ||--o{ Order : places
@enduml

The ||--o{ notation follows standard crow's-foot syntax: one customer to zero-or-many orders.

Tips for Clean Diagrams

• Use aliases for long names: participant "Payment Gateway" as PG keeps your arrows readable.
• Add a theme for a quick style upgrade: !theme cerulean-outline (or plain, sketchy, spacelab, and others) placed right after @startuml.
• Keep diagrams small and focused. If a sequence diagram needs more than ~8–10 participants, it's usually a sign to split it into two diagrams.
• Store diagrams next to your code. Since they're just text, a .puml file can live in your repo and get reviewed like any other change.

Wrapping Up

PlantUML won't replace a polished design tool when you need pixel-perfect illustrations, but for the diagrams developers actually need day to day — flows, architectures, schemas, sequences — writing a few lines of text is faster than dragging boxes, and you get a diff-friendly file as a bonus.

Try pasting any of the examples above into the online editor and start tweaking — that's the fastest way to get a feel for the syntax.