PlantUML Examples: Diagrams, Syntax, and Workflows

PlantUML turns concise text into diagrams, which makes architecture and design documentation easier to inspect, revise, and keep consistent. The fastest way to learn it is not to memorize every command. Start with a small working example, choose the diagram type that matches your question, and add detail only when that detail helps the reader make a decision.

This guide provides copyable PlantUML examples for the most useful diagram families: sequence, class, entity-relationship, C4, activity, component, deployment, and state diagrams. It also explains the shared syntax, styling choices, layout behavior, and editor workflow that connect those examples. PlantUML's official site lists both UML and non-UML diagram types and documents PNG, SVG, LaTeX, EPS, and sequence-only text output, so one textual workflow can serve many publishing environments (PlantUML, “Open-source tool that uses simple textual descriptions,” retrieved July 24, 2026).

Each PlantUML source block on this page can switch between the editable source and its rendered diagram preview. When you find a useful starting point, open the OnUML editor, choose PlantUML mode, and paste the source to adapt it.

OnUML generates PlantUML previews and exports by sending the encoded source to its configured PlantUML rendering service. Do not place passwords, API keys, access tokens, private endpoints, or confidential architecture details in the source.

Key Takeaways

• Every complete PlantUML source block begins with @startuml and ends with @enduml.
• Choose a diagram by the question: sequence for interactions over time, class or ER for structure, C4 or component for architecture, activity for process, and state for lifecycle.
• Keep the source as the maintainable artifact; export PNG for convenient sharing and SVG when scaling and crisp text matter.
• Let automatic layout handle the first draft. Add direction, grouping, colors, or themes only to communicate meaning.
• The examples below are deliberately small, so you can paste one into an editor and extend it immediately.
• Use each source block's preview control to compare the text with the rendered result before editing it.

Table of Contents

• What is a PlantUML diagram?
• How does PlantUML syntax work?
• Which PlantUML diagram should you choose?
• Sequence diagram example
• Class diagram example
• ER diagram example
• C4 diagram example
• Activity, component, deployment, and state examples
• Colors, themes, and layout
• Saving and exporting
• Common problems
• FAQ

What Is a PlantUML Diagram?

A PlantUML diagram is an image generated from a textual description of elements and their relationships. Instead of manually positioning every shape, you describe participants, classes, systems, activities, or states, and the renderer calculates their visual arrangement.

The smallest useful example is:

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

The source is readable even before it is rendered. In OnUML, a reviewer can inspect the text, identify that a message or relationship changed, and discuss the same source that produces the preview. The saved OnUML project remains editable, while PNG and SVG are rendered outputs.

PlantUML is broader than its name suggests. In addition to standard UML diagrams such as sequence, class, activity, component, deployment, state, object, use-case, and timing diagrams, its official documentation includes formats such as entity-relationship and JSON or YAML visualizations (PlantUML supported diagrams). You do not need all of them. A focused set of diagram types covers most software documentation.

How Does PlantUML Syntax Work?

PlantUML syntax is declarative: identify elements, describe connections, and optionally add labels or presentation rules. The renderer decides the coordinates.

Most sources share four ideas:

1. @startuml starts a diagram and @enduml closes it.
2. Keywords declare elements such as participant, class, entity, component, or state.
3. Arrow notation expresses a message, relationship, transition, or dependency.
4. Commands such as title, note, skinparam, and !theme refine presentation.

Here is a mixed component example:

@startuml
title Order Processing

actor Customer
component "Web App" as Web
component "Order API" as API
database "Orders" as DB

Customer --> Web: Place order
Web --> API: POST /orders
API --> DB: Save order
@enduml

Aliases such as Web, API, and DB keep relationships short while preserving descriptive labels in the output. Quotes are useful for labels containing spaces. A colon generally introduces the text shown on a relationship.

Arrows are context-sensitive. In a sequence diagram, -> represents a message in time order. In a component diagram, it usually represents a dependency or communication direction. In a class diagram, specialized symbols distinguish inheritance, implementation, composition, aggregation, and dependency. Read the arrow in the context of its diagram type rather than assuming one universal meaning.

Comments can be useful when the source needs maintenance notes. A single quote starts a one-line PlantUML comment:

@startuml
' 该别名用于缩短后续关系定义
component "Payment Service" as Payment
database "Payment Records" as Records
Payment --> Records
@enduml

Which PlantUML Diagram Should You Choose?

Choose the diagram that answers the reader's question with the least notation. A common documentation mistake is selecting the most familiar diagram rather than the most informative one.

A diagram should have one primary purpose. If you need to show an order workflow, for example, use a sequence diagram for the runtime conversation, a class or ER diagram for the data structure, and a state diagram for the order lifecycle. Combining all three questions into one view usually creates a diagram that is technically dense but operationally weak.

If your decision is between text-based tools rather than diagram types, see the existing Mermaid vs PlantUML comparison. The rest of this guide stays focused on PlantUML itself.

PlantUML Sequence Diagram Example

A sequence diagram shows who communicates, what message is exchanged, and in which order the interaction occurs. It is a strong choice for login flows, API requests, background jobs, event processing, and service-to-service behavior.

@startuml
title Sign-in Flow
autonumber

actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Store" as DB

User -> Web: Submit credentials
Web -> Auth: Authenticate
Auth -> DB: Find user
DB --> Auth: User record

alt Credentials are valid
  Auth --> Web: Access token
  Web --> User: Open dashboard
else Credentials are invalid
  Auth --> Web: Authentication error
  Web --> User: Show error
end
@enduml

This example introduces explicit participants, synchronous messages, dotted return arrows, automatic numbering, and an alt/else conditional group. PlantUML also supports opt, loop, par, break, critical, and general group blocks. The official sequence-diagram reference confirms that participants may be inferred from messages, but explicit declarations give you control over their type, label, alias, and display order (PlantUML sequence diagram documentation).

Keep each message label at one consistent abstraction level. Authenticate and Find user work together; a low-level method signature placed beside a vague business phrase would make the timeline harder to interpret. When a flow becomes tall, split independent scenarios or use reference blocks before reaching for page breaks.

For a deeper walkthrough of authentication, REST API interactions, activations, and grouped alternatives, continue to PlantUML sequence diagram examples.

PlantUML Class Diagram Example

A class diagram describes the static structure of software: types, their members, and their relationships. Use it to discuss a domain model, public interfaces, ownership, or a proposed code organization.

@startuml
title Small E-commerce Domain
hide empty members

class Customer {
  +id: UUID
  +email: String
  +placeOrder(): Order
}

class Order {
  +number: String
  +status: OrderStatus
  +total(): Money
}

class OrderLine {
  +quantity: int
  +unitPrice: Money
}

enum OrderStatus {
  Draft
  Confirmed
  Shipped
}

Customer "1" --> "0..*" Order: places
Order "1" *-- "1..*" OrderLine
Order --> OrderStatus
@enduml

The quoted values near each end express multiplicity. The filled diamond in *-- represents composition: the order owns its order lines in this model. PlantUML's class reference distinguishes extension (<|--), interface realization (<|..), composition (*--), aggregation (o--), and dependencies such as --> or ..> (PlantUML class diagram documentation).

Do not use every available relationship merely because PlantUML can render it. Add a relationship only if it affects the design conversation. A conceptual domain diagram may omit methods; an API-oriented diagram may show only public operations; a code-generation model may need exact types and visibility.

For relationship notation, multiplicity, packages, interfaces, and a larger domain model, see PlantUML class diagram relationships and examples.

PlantUML ER Diagram Example

An entity-relationship diagram focuses on persistent data, keys, and cardinality. It resembles a class diagram, but its vocabulary is about tables or conceptual entities rather than runtime objects and behavior.

@startuml
title Store Data Model

entity CUSTOMER {
  * customer_id : UUID <<PK>>
  --
  email : VARCHAR
}

entity PURCHASE_ORDER {
  * order_id : UUID <<PK>>
  --
  customer_id : UUID <<FK>>
  created_at : TIMESTAMP
}

entity ORDER_LINE {
  * order_line_id : UUID <<PK>>
  --
  order_id : UUID <<FK>>
  quantity : INTEGER
}

CUSTOMER ||--o{ PURCHASE_ORDER
PURCHASE_ORDER ||--|{ ORDER_LINE
@enduml

The crow's-foot-style endpoints communicate cardinality compactly. Here, one customer may have zero or more purchase orders, while each order contains one or more lines. Keeping primary and foreign keys visible makes the example useful in schema reviews; omitting implementation-specific columns can keep a conceptual ERD readable.

Use an ER diagram when data integrity and cardinality are the subject. Use a class diagram when object responsibilities, methods, inheritance, or domain behavior matter. The dedicated PlantUML ER diagram and ERD guide explains notation choices and builds a more complete database model.

PlantUML C4 Diagram Example

C4 diagrams describe software architecture at progressively closer levels: system context, containers, components, and—when useful—code. PlantUML can use its standard-library C4 macros through !include.

@startuml
!include <C4/C4_Context>

title Online Store — System Context

Person(customer, "Customer", "Browses products and places orders")
System(store, "Online Store", "Handles catalog, checkout, and order tracking")
System_Ext(payments, "Payment Provider", "Authorizes card payments")

Rel(customer, store, "Uses", "HTTPS")
Rel(store, payments, "Requests payment authorization", "HTTPS")
@enduml

This context view intentionally avoids databases, queues, frameworks, and internal services. It establishes the system boundary and external relationships. A container view can then reveal web applications, APIs, data stores, and messaging systems; a component view can zoom into one container.

PlantUML distributions include a standard library, and the official documentation explains that libraries can be referenced with the <...> include syntax (PlantUML Standard Library). Because remote or renderer-specific installations can vary, verify that the C4 library is available in the environment used by your team.

The PlantUML C4 context, container, and component examples uses one system across all three levels, making the boundary between views easier to understand.

More Useful PlantUML Examples

The four previous types cover many software-design tasks, but process, module, infrastructure, and lifecycle questions need different views.

Activity diagram for a decision-driven process

@startuml
start
:Validate cart;
if (Cart is valid?) then (yes)
  :Reserve inventory;
  :Request payment;
else (no)
  :Show validation error;
endif
stop
@enduml

Activity diagrams are effective when decisions and work steps matter more than which service sends each message. If ownership matters too, add partitions or create a complementary sequence diagram.

Component diagram for dependencies

@startuml
component "Checkout UI" as UI
component "Order API" as API
component "Payment Adapter" as Payment
database "Order DB" as DB

UI --> API
API --> Payment
API --> DB
@enduml

A component diagram is useful for module boundaries and dependencies. Keep labels meaningful: “uses” or a protocol name often tells readers more than an unlabeled arrow.

Deployment diagram for runtime placement

@startuml
node "Cloud Region" {
  node "Application Cluster" {
    artifact "Order API"
  }
  database "Managed Database"
}

"Order API" --> "Managed Database": TLS
@enduml

Deployment diagrams answer where artifacts run and how nodes communicate. They are not substitutes for infrastructure-as-code; they summarize the architecture at the level needed for discussion.

State diagram for an entity lifecycle

@startuml
[*] --> Draft
Draft --> Confirmed: confirm
Confirmed --> Shipped: dispatch
Draft --> Cancelled: cancel
Confirmed --> Cancelled: refund
Shipped --> [*]
Cancelled --> [*]
@enduml

State diagrams are particularly valuable when rules depend on the current state. Label transitions with events or commands, and use guards when the condition is important.

How to Style and Arrange PlantUML Diagrams

Style should clarify categories, emphasis, or ownership—not compensate for an unclear model. Begin with the default rendering. Then make the smallest presentation change that helps the intended reader.

Themes provide a coherent baseline:

@startuml
!theme plain

actor User
component "Web App" as Web
component "API" as API

User --> Web
Web --> API
@enduml

Element colors can distinguish roles:

@startuml
participant User #DCEBFF
participant "Order Service" as Order #FFF0C2
database Database #E3F7E8

User -> Order: Create order
Order -> Database: Insert order
@enduml

Use color redundantly with labels or stereotypes so meaning does not depend on color perception. Check contrast in both light and dark viewing contexts when diagrams will be embedded in a themed site.

For many non-sequence diagrams, left to right direction can create a wider view:

@startuml
left to right direction

actor Customer
rectangle Store {
  component Catalog
  component Checkout
}
Customer --> Catalog
Catalog --> Checkout
@enduml

Automatic layout is a constraint solver, not a drawing canvas. Ordering declarations, simplifying cross-links, grouping related elements, and changing direction are usually more stable than trying to force exact positions. For reusable palettes and accessible styling, use PlantUML colors and themes. For direction, spacing, grouping, and difficult nested boxes, see PlantUML layout and nested boxes.

How to Save and Export a PlantUML Diagram in OnUML

A simple workflow is:

1. Create or paste the source into OnUML's PlantUML editor.
2. Render a preview and correct syntax errors.
3. Sign in and save the OnUML project when you need to continue editing it later.
4. Export the format required by the destination.

Choose PNG for broad compatibility in chat, documents, and issue trackers. Choose SVG for responsive web pages, zooming, and crisp text. In OnUML, verify the current preview and use the PNG or SVG action in the editor toolbar.

Keep the OnUML project when future edits matter. A downloaded image is a publishing asset and cannot be edited as PlantUML source.

Follow the complete PlantUML export guide for OnUML projects, browser drafts, PNG/SVG downloads, and public sharing.

Common PlantUML Problems and How to Avoid Them

Most PlantUML problems fall into four categories: syntax, renderer capabilities, layout expectations, and output handling.

A valid source produces no visible change

Confirm that you are editing the source currently being rendered and that the preview refreshed. If an !include is involved, verify that the renderer can resolve it. Reduce the source to a small @startuml/@enduml example, then restore sections until the problem returns.

newpage appears not to work

newpage describes a page split at the PlantUML language level, but OnUML currently previews and exports one image per diagram tab. Use the PlantUML newpage troubleshooting guide to split long sequences into tabs that remain visible and downloadable.

The diagram will not stay in an exact position

PlantUML optimizes an automatically calculated graph. If precise manual placement is a core requirement, repeated hidden links and layout tricks can make the source fragile. First simplify the relationship graph, use packages or rectangles to express grouping, and consider whether the desired position carries real information.

Drag and drop is missing

PlantUML itself is text-first. Editors may add previews, templates, forms, or other visual conveniences, but a fully free-form WYSIWYG canvas is a different interaction model. The PlantUML WYSIWYG editor and drag-and-drop guide explains what to expect and how to choose between text-first and visual editing.

A large diagram becomes unreadable

Do not solve every size problem by shrinking fonts. Split the view by audience and question. Use a context diagram for scope, a container or component diagram for architecture, a sequence diagram for one scenario, and a class or ER diagram for one bounded domain. Multiple connected views preserve useful detail better than one “everything diagram.”

A Practical Workflow for Maintainable Diagrams

Start each diagram with a one-sentence question. “How does checkout handle an authorization failure?” is testable; “Document checkout” is not. The question determines the diagram type and the elements worth showing.

Then follow this loop:

1. Model the minimum path. Add only the central participants or elements and their essential relationships.
2. Render early. Syntax and visual complexity are easier to correct while the source is small.
3. Add one kind of detail at a time. Introduce alternatives, cardinalities, protocols, or notes only where they resolve likely ambiguity.
4. Review with the intended audience. A security reviewer, product manager, database engineer, and application developer need different details.
5. Give the saved project a clear owner and title. Documentation without a clear maintenance boundary ages quickly.
6. Use external automation only when your team already maintains it. OnUML provides interactive preview and PNG/SVG export; CI rendering is a separate workflow outside OnUML.

The most maintainable PlantUML example is not the most elaborate one. It is the smallest source that reliably answers the question and can be changed without reverse-engineering a visual canvas.

Frequently Asked Questions

Can PlantUML generate SVG?

Yes. PlantUML's official documentation lists SVG alongside PNG and other outputs. SVG is often the better web format when the diagram must scale without losing text clarity.

Is PlantUML only for UML diagrams?

No. PlantUML supports traditional UML types and several non-UML formats. Its official supported-diagrams list includes entity-relationship, mind map, work breakdown structure, JSON, YAML, network, and other diagram families.

Should I use a class diagram or an ER diagram?

Use a class diagram for software types, behavior, and object relationships. Use an ER diagram for persistent entities, keys, and cardinality. When a domain model and database schema differ, maintaining separate views is clearer than forcing both into one notation.

Can I control every element's exact position?

Not in the same way as a free-form drawing tool. PlantUML uses automatic layout engines. You can influence direction, grouping, ordering, spacing, and some relationships, but exact coordinates are not the normal authoring model.

Does newpage create one multipage image?

No. newpage describes separate rendered pages rather than one multipage image. OnUML currently exposes one rendered image per diagram tab, so use separate tabs when every section must be previewed and exported.

Continue Learning

The best next step is to choose the guide closest to the question you need to answer and adapt its complete example.

Diagram guides:

• PlantUML sequence diagram syntax and real-world examples
• PlantUML class diagram relationships and examples
• PlantUML ER diagram and ERD examples
• PlantUML C4 context, container, and component diagrams

Styling and layout:

• PlantUML colors and themes guide
• PlantUML layout, direction, spacing, and nested boxes

Editor and export workflows:

• export PlantUML as PNG or SVG in OnUML
• fix PlantUML newpage and multi-output problems
• PlantUML WYSIWYG and drag-and-drop editing options

PlantUML works best when the text remains simple enough to review and the rendered view remains focused enough to support a decision. Copy the smallest relevant example, replace its domain terms, and expand it only when a reader needs more information.

Official Sources

• PlantUML homepage and supported diagram types
• PlantUML Quick Start Guide
• PlantUML Sequence Diagram documentation
• PlantUML Class Diagram documentation
• PlantUML Standard Library documentation