Plantuml Diagram Code Reference Guide for Uml Syntax

If you've ever stared at a blank screen trying to turn a software design idea into a diagram, you know the frustration. PlantUML lets you skip the drag-and-drop and write diagrams using plain text code but only if you know the syntax. That's where a solid reference guide makes all the difference. Whether you're documenting a system architecture, mapping out a sequence flow, or sketching a use case, having the right PlantUML code patterns at your fingertips saves hours of guesswork and broken diagrams.

What is PlantUML, and why use code to make diagrams?

PlantUML is an open-source tool that generates UML diagrams from a simple, text-based language. Instead of clicking shapes in a drawing tool, you write short lines of code that describe your diagram. A rendering engine then converts that code into an image PNG, SVG, or other formats.

Why bother with code when visual editors exist? A few reasons:

Version control friendly. Plain text plays nicely with Git. You can track changes, review diffs, and merge diagram updates like any other source file.
Fast editing. Changing an arrow direction or renaming a class takes seconds no wrestling with a canvas.
Reproducible. The same code always produces the same output. No layout surprises when a teammate opens your file.
Tool integration. PlantUML works inside VS Code, IntelliJ, Confluence, GitHub, and many wikis.

According to the official PlantUML documentation, the tool supports dozens of diagram types from basic flowcharts to complex deployment diagrams. But knowing the tool exists and knowing how to write valid syntax are two different things.

What types of diagrams can you create with PlantUML?

PlantUML supports a wide range of diagram types. Here are the ones developers use most often:

Sequence diagrams show how objects or components interact over time
Use case diagrams capture actor goals and system boundaries
Class diagrams model object structures, attributes, and relationships
Activity diagrams represent workflows, decisions, and parallel processes
State diagrams track how an object changes states based on events
Component diagrams map software modules and their dependencies
Deployment diagrams show how software runs on physical or virtual infrastructure
Object diagrams snapshot a system's state at a specific moment
Timing diagrams display state changes over a time axis
Mind maps and wireframes non-UML diagrams PlantUML also handles

Each diagram type has its own set of keywords and rules. A sequence diagram uses -> arrows between participants, while a class diagram uses class, interface, and relationship connectors like -- or <|... Mixing them up is one of the most common errors beginners hit.

How do you write a basic PlantUML diagram?

Every PlantUML diagram follows the same skeleton:

Open with @startuml (or @startmindmap, @startsalt for other types).
Write your diagram content using type-specific syntax.
Close with @enduml.

Here's a minimal sequence diagram:

@startuml
actor User
User -> Server: Send request
Server --> User: Return response
@enduml

That's six lines, and it produces a clean diagram showing a user sending a request to a server and getting a response back. The arrow style (-> vs -->) controls whether the line is solid or dashed, and the text after the colon becomes the message label.

For a deeper breakdown of sequence notation, check out our guide on UML sequence diagram notation.

Where can you find PlantUML syntax for specific diagram types?

PlantUML's syntax varies enough between diagram types that you'll regularly need a reference. Here's where to look:

Official PlantUML language reference at plantuml.com covers every keyword and option.
Our PlantUML diagram code reference compiles the most-used syntax patterns into one place with examples.
IDE plugins like the PlantUML extension for VS Code provide inline previews so you can test syntax as you type.
Community examples on GitHub repositories and forums show real-world usage patterns.

What are the most common PlantUML syntax mistakes?

Even experienced developers run into these pitfalls:

Forgetting @enduml. Without it, the renderer won't produce output. It sounds obvious, but in large code blocks it's easy to miss.
Using the wrong arrow syntax for the diagram type. Class diagrams use different connectors than sequence diagrams. Copying syntax from one type to another almost always breaks things.
Missing quotes around labels with special characters. If your message text contains colons, brackets, or other reserved characters, wrap it in quotes.
Confusing actor with participant. In sequence diagrams, actor renders a stick figure while participant renders a box. Pick the one that matches your intent.
Not defining aliases before using them. If you write Alice -> Bob without declaring actor Alice or participant Bob first, PlantUML auto-creates them but you lose control over styling and order.

How do activity diagrams work in PlantUML?

Activity diagrams model workflows: start points, actions, decisions, forks, joins, and end points. PlantUML uses a clean syntax for these:

@startuml
start
:User clicks login;
if (Valid credentials?) then (yes)
:Show dashboard;
else (no)
:Show error message;
endif
stop
@enduml

The start and stop keywords create the filled circle and bullseye symbols. Actions are wrapped in colons. Diamonds handle branching. If you're new to this diagram type, our beginner's guide to UML activity diagram syntax walks through each element step by step.

Can you customize how PlantUML diagrams look?

Yes, and this is where PlantUML surprises many people. You can control colors, fonts, line styles, and layout with skin parameters and themes.

Common customization options:

Themes: Use !theme cerulean or !theme sketchy at the top of your diagram for instant style changes.
Skin parameters: Commands like skinparam backgroundColor #FEFEFE or skinparam ArrowColor #333333 fine-tune individual visual properties.
Stereotypes and sprites: Add icons to elements using built-in or custom sprites for more expressive diagrams.
Legend and notes: legend right and note left of ClassName add contextual information directly to the diagram.

Customization is useful, but don't overdo it. A clean, readable diagram with default styling communicates better than a heavily styled one that's hard to scan.

What's the best way to organize PlantUML in a real project?

For small projects, a single .puml file per diagram works fine. As your project grows, consider these practices:

One file per diagram. Name files descriptively: login-sequence.puml, order-processing-activity.puml.
Use includes for shared elements. PlantUML's !include directive lets you pull in common definitions standard actors, color themes, or reusable component definitions.
Store diagrams near the code they describe. A sequence diagram in the same folder as the service it documents makes it easier to keep them in sync.
Automate rendering in CI/CD. Use the PlantUML JAR or Docker image in your build pipeline to generate updated images on every commit.
Use the C4 model extension for architecture diagrams at different abstraction levels context, container, component, and code.

How do you get PlantUML running locally?

There are several ways to write and render PlantUML:

VS Code with the PlantUML extension. Install it from the marketplace, write your .puml files, and press Alt+D to preview. You'll need Java installed or a remote rendering server configured.
IntelliJ IDEA. The PlantUML integration plugin provides live previews directly in the IDE.
Command line. Download the PlantUML JAR file and run java -jar plantuml.jar diagram.puml to generate an image.
Online editor. The PlantUML online server lets you write and render diagrams in the browser with no setup. It's useful for quick experiments and sharing links.

For most developers, the VS Code extension strikes the best balance of convenience and capability. It supports syntax highlighting, auto-completion, and live preview everything you need for daily diagram work.

Quick-reference checklist for writing PlantUML diagrams

Start every diagram with @startuml and end with @enduml
Declare your participants, actors, or classes before referencing them in relationships
Match arrow syntax to the diagram type (solid vs. dashed, forward vs. backward)
Use quotes around labels that contain special characters
Test your diagram in an online editor or live preview before committing
Keep diagram files small and focused one diagram per file
Add notes and legends to explain non-obvious parts of your diagram
Use !include to reuse common definitions across diagrams
Store .puml source files in version control alongside your code
Automate image generation with CI/CD so documentation stays current

Pick one diagram you need right now a sequence diagram for an API call, an activity flow for a user journey, or a class diagram for a new module. Open an online editor, type out the code using patterns from this reference, and render it. You'll learn faster by doing than by reading, and you'll have a working diagram to show for it.