If you've ever needed to turn a messy process or workflow into a clean visual diagram, you know the pain of dragging boxes around in a GUI tool. PlantUML lets you describe diagrams using plain text code, and flowcharts are one of the most common diagrams people build with it. But the syntax has quirks, and finding the right reference for flowchart-specific commands can save you hours of trial and error. This article covers what you need to know about PlantUML flowchart diagram code reference the syntax, the symbols, the shortcuts, and the mistakes that trip people up.

What Is PlantUML and Why Use It for Flowcharts?

PlantUML is an open-source tool that generates diagrams from a simple text-based language. You write code, and PlantUML renders it into an image. For flowcharts, this means you can version-control your diagrams alongside your code, collaborate through pull requests, and update visuals without touching a mouse.

Unlike tools such as Lucidchart or draw.io, PlantUML diagrams live as plain text files. That makes them easy to search, diff, and maintain. Developers use them in README files, documentation wikis, architecture decision records, and CI pipelines that auto-generate updated diagrams.

How Does PlantUML Flowchart Syntax Actually Work?

A PlantUML flowchart starts with the @startuml tag and ends with @enduml. Between those tags, you define nodes and the connections between them. Here's a basic example:

@startuml
start
:Receive order;
:Validate payment;
if (Payment valid?) then (yes)
  :Process order;
else (no)
  :Reject order;
endif
stop
@enduml

For a deeper walkthrough of the full syntax options, check out the PlantUML flowchart diagram code reference we've put together with detailed examples of every supported element.

What Are the Basic Node Shapes in PlantUML Flowcharts?

PlantUML Activity Diagram syntax (which is what you use for flowcharts) supports several built-in shapes through different notation styles:

  • Rectangles (default actions) Use :Action text; to create a rectangular process box.
  • Diamonds (decisions) Use if (condition?) then (yes) else (no) endif for branching logic.
  • Rounded rectangles Use :Start action; or declare them with start and stop keywords for terminal nodes.
  • Notes Add note left: Your note text or note right: Your note text next to any activity.
  • Partitions Group related activities using partition "Name" { ... }.

You can also use the more flexible new activity diagram syntax which supports custom shapes through stereotyping, like :My Action; combined with skinparam commands to control appearance.

Common Shape Shortcuts

If you're working with the newer syntax (sometimes called "beta" syntax), you can define node shapes directly:

  • (shape) = text Declares a named node
  • |swimlane| Creates swimlane headers
  • #color Adds background color to a node

For beginners who want a solid foundation before diving into advanced features, our beginner's guide to flowchart code syntax walks through these basics step by step.

How Do You Connect Nodes in a PlantUML Flowchart?

Connections depend on which syntax version you're using. In the classic Activity Diagram syntax, arrows are implicit PlantUML draws them based on the order of your statements. In the newer syntax, you use explicit arrow notation:

  • A --> B Simple arrow from A to B
  • A --> B : label Arrow with a label
  • A --> B #color Arrow with color
  • A -[#red]> B Colored arrow using inline notation
  • A -[dashed]-> B Dashed line connection

You can also use goto and label for jumping across distant parts of the diagram, though this can quickly reduce readability if overused.

What Are the Most Common Mistakes When Writing PlantUML Flowchart Code?

After working with PlantUML across dozens of projects, here are the errors I see most often:

1. Mixing Old and New Syntax

PlantUML has two Activity Diagram syntaxes. The classic one uses start/stop/if keywords. The newer one uses arrow-based notation with |swimlane| support. Mixing them in one diagram causes rendering errors. Pick one style and stick with it.

2. Forgetting the Semicolon

In the classic syntax, every action statement needs to end with a semicolon: :Do something;. Missing this is the number one cause of parsing errors for newcomers.

3. Overcomplicating the Diagram

A flowchart with 40+ nodes becomes unreadable regardless of the tool. Break complex processes into sub-diagrams and link between them using !include directives.

4. Not Using Skinparam for Styling

PlantUML defaults are functional but plain. Using skinparam commands lets you control fonts, colors, arrow styles, and spacing. Skipping this makes diagrams harder to read, especially in presentations.

5. Ignoring the Rendering Engine

PlantUML supports multiple rendering engines including Graphviz (default for some diagram types), Smetana (a pure-Java alternative), and the built-in activity diagram renderer. If your flowchart isn't rendering, check whether you need Graphviz installed.

How Can You Style and Customize PlantUML Flowcharts?

PlantUML gives you several ways to control the look of your flowcharts without leaving the text-based workflow:

  • skinparam commands Global style settings like skinparam activityBackgroundColor #f0f0f0 or skinparam ArrowColor #333.
  • Stereotypes Apply named styles to specific elements using <<highlight>> tags.
  • Colors inline Use #lightgreen or hex values directly on nodes and arrows.
  • Creole markup Add bold, italic, and other formatting within node text using Creole syntax.

Keep a quick reference handy when you're building diagrams regularly. Our flowchart syntax cheat sheet for developers is designed for exactly that a fast lookup when you can't remember whether it's -[#red]> or --[#red]>.

When Should You Use PlantUML Flowcharts Over Other Diagram Types?

PlantUML supports many diagram types sequence diagrams, class diagrams, state diagrams, and more. Flowcharts (Activity Diagrams) work best when you're documenting:

  • Business process workflows with decision points
  • Approval pipelines with multiple branches
  • Technical processes like deployment steps or error handling paths
  • User journey flows for product or UX documentation
  • Incident response runbooks that need clear step-by-step logic

If your diagram is mostly about message exchanges between actors, a sequence diagram is usually clearer. If it's about object relationships, use a class diagram. The flowchart shines when the core story is about what happens next and which path gets taken.

Practical Checklist for Writing PlantUML Flowchart Code

  1. Start every diagram with @startuml and end with @enduml
  2. Choose your syntax style (classic or beta) and stay consistent
  3. Use :action; for process steps and if/then/else/endif for decisions
  4. Label every decision branch clearly don't leave blank arrow labels
  5. Keep diagrams under 25 nodes when possible; split larger flows into linked sub-diagrams
  6. Add a title with title My Flowchart Name at the top
  7. Use skinparam to set consistent colors and fonts across your project
  8. Test your code in the PlantUML online server before committing it
  9. Store .puml files in version control alongside the code they document
  10. Set up a CI step or documentation plugin to auto-render diagrams on commit

Next step: Pick one workflow or process from your current project, write it out as PlantUML flowchart code using the checklist above, render it in the online server, and add it to your project documentation. The first diagram is always the hardest after that, you'll find yourself reaching for PlantUML text instead of a drawing tool almost every time.