If you've ever tried to explain a system, process, or conversation flow to someone and wished you could just draw it quickly that's exactly what PlantUML solves. Instead of dragging boxes around in a graphic editor, you write simple text and get a diagram. For beginners, seeing real PlantUML diagram code examples is the fastest way to learn. One working example teaches more than pages of theory. This article walks you through the most common diagram types, shows you copy-paste-ready code, and flags the mistakes that trip up new users.

What is PlantUML and why write diagrams in plain text?

PlantUML is an open-source tool that turns plain text descriptions into UML diagrams. You write code in a simple markup language, and PlantUML renders it into sequence diagrams, class diagrams, use case diagrams, activity diagrams, and more. The whole thing runs from text no mouse dragging, no alignment headaches, no proprietary file formats.

Developers and technical writers use it because text-based diagrams live alongside your code. You can version them with Git, review changes in pull requests, and update them without opening a separate design tool. If you're new to UML notation itself, our UML syntax reference guide covers the foundational notation before you start coding diagrams.

How do you get started with PlantUML?

You need two things: a way to write PlantUML code and a way to render it. Here are the most common setups for beginners:

  • Online editor: The official PlantUML online server lets you paste code and see results instantly. No installation needed.
  • VS Code extension: Install the "PlantUML" extension by jebbs. Open a .puml file, write your code, and preview with Alt+D.
  • IntelliJ IDEA plugin: PlantUML Integration is built into many JetBrains IDEs or available as a plugin.
  • Command line: Download the PlantUML JAR file and render diagrams from the terminal.

For your first few diagrams, the online editor is the easiest path. Once you're comfortable, move to an IDE extension so your diagrams live next to your code.

What does basic PlantUML code look like?

Every PlantUML diagram starts with an opening tag and ends with a closing tag. Here's the skeleton:

@startuml
... your diagram code here ...
@enduml

That's it. Everything between those two lines defines your diagram. Let's look at real examples for each common diagram type.

Can you show me a simple sequence diagram?

Sequence diagrams show how actors and systems exchange messages over time. They're the most popular PlantUML diagram type, and for good reason they're straightforward to write.

@startuml
actor User
User -> Browser: Enter URL
Browser -> Server: HTTP GET request
Server -> Database: Query data
Database --> Server: Return results
Server --> Browser: HTML response
Browser --> User: Display page
@enduml

This creates a diagram with a User, Browser, Server, and Database. Arrows show the direction of each message, and the text after the colon is the label. The double arrow (-->) draws a dashed return line.

Sequence diagrams have more depth than this basics example. If you want to understand how to add loops, alt blocks, and activation bars, our article on sequence diagram code structure breaks that down step by step.

How do you draw a use case diagram?

Use case diagrams show what a system does from a user's perspective. They're useful for requirements discussions and early-stage planning.

@startuml
left to right direction
actor Customer
actor Admin

rectangle "Online Store" {
  usecase "Browse Products" as UC1
  usecase "Place Order" as UC2
  usecase "Manage Inventory" as UC3
}

Customer --> UC1
Customer --> UC2
Admin --> UC3
@enduml

The left to right direction command flips the layout so actors appear on the sides instead of the top. The rectangle groups related use cases inside a system boundary. Aliases like as UC1 let you reference the use case later without retyping its full label.

What about class diagrams?

Class diagrams describe the structure of a system the classes, their attributes, methods, and how they relate to each other.

@startuml
class User {
  - name: String
  - email: String
  + login(): void
  + logout(): void
}

class Order {
  - orderId: int
  - date: Date
  + calculateTotal(): float
}

User "1" --> "0.." Order : places
@enduml

A minus sign (-) marks private members. A plus sign (+) marks public members. The notation "1" --> "0.." defines a one-to-many relationship. The text after the colon is the relationship label.

How do you make an activity diagram?

Activity diagrams show workflows and decision paths. They're great for mapping business processes or algorithm logic.

@startuml
start
:Receive order;
if (Payment valid?) then (yes)
  :Process order;
  :Ship item;
else (no)
  :Send payment error;
endif
stop
@enduml

PlantUML draws the diamond-shaped decision node automatically when you use the if/then/else/endif syntax. Each action goes inside colons and ends with a semicolon.

How do you create a component diagram?

Component diagrams show how a system is split into modules and how those modules connect. They're common in architecture documentation.

@startuml
package "Frontend" {
  [Web App]
  [Mobile App]
}

package "Backend" {
  [API Server]
  [Auth Service]
}

database "PostgreSQL" as db

[Web App] --> [API Server]
[Mobile App] --> [API Server]
[API Server] --> [Auth Service]
[API Server] --> db
@enduml

Square brackets define components. The package keyword groups them visually. The database keyword renders a cylinder shape, which is the standard symbol for databases in UML.

What mistakes do beginners make with PlantUML code?

After working with dozens of beginners, these are the errors that come up most often:

  • Forgetting the @enduml tag. Every diagram needs both @startuml and @enduml. Without the closing tag, PlantUML won't render anything.
  • Using wrong arrow syntax. A right arrow (->) is different from a dashed arrow (-->). Mixing them up changes the diagram meaning in UML.
  • Missing semicolons in activity diagrams. Each action line must end with a semicolon. Without it, PlantUML throws a syntax error.
  • Special characters breaking the parser. If your label text contains quotes, dashes, or brackets, wrap the entire label in quotes: "Contains a (special) character".
  • Assuming the diagram type is auto-detected. PlantUML infers the diagram type from your code, but ambiguous code leads to unexpected results. Be clear with your syntax.
  • Overcomplicating the first version. Start with the simplest version that shows the idea. Add styling, notes, and colors after the structure works.

How do you add notes, colors, and styling?

Once your diagram structure works, you can make it easier to read with a few additions:

  • Notes: note right of User: This is a note attaches a note to an element.
  • Colors: #lightblue after an element name sets its background color.
  • Title: title My Diagram Title adds a heading above the diagram.
  • Footer: footer Page %page% of %lastpage% adds page info.
  • Comments: Lines starting with a single quote (') are ignored by the renderer.

Styling is nice, but get the logic right first. A clean diagram with no colors communicates better than a messy one with pretty formatting.

Where can you find more PlantUML diagram code examples?

The best places to find working examples after you've got the basics:

The official site is dense, but it's the most complete and accurate reference when you need to look up a specific syntax element.

Quick checklist: your first PlantUML diagram in under 5 minutes

  1. Open the PlantUML online editor.
  2. Paste this code:
    @startuml
    Alice -> Bob: Hello
    Bob --> Alice: Hi there
    @enduml
  3. Click "Submit" and see your first sequence diagram.
  4. Change the names and messages to match your actual system.
  5. Add more participants (lines like Charlie -> Alice: Update).
  6. Copy the code into a .puml file in your project.
  7. Commit it to version control so your team can find it later.

Start with sequence diagrams they're the most forgiving syntax and the most useful for explaining how things work. Once you've built three or four, try a class diagram or activity diagram. You'll find that the patterns repeat, and each new diagram type gets easier.