Sequence diagram

Sequence diagrams in PlantUML are defined entirely in text. You write the participants and the messages they exchange; the layout, spacing, and arrows are handled for you.

See common commands for features available across all diagram types.

Basic Examples

In PlantUML sequence diagrams, the -> sequence denotes a message sent between two participants, which are automatically recognized and do not need to be declared beforehand.

Utilize dotted arrows by employing the --> sequence, offering a distinct visualization in your diagrams.

To improve readability without affecting the visual representation, use reverse arrows like <- or <--. However, be aware that this is specifically for sequence diagrams and the rules differ for other diagram types.

Declaring participant

If the keyword participant is used to declare a participant, more control on that participant is possible.

The order of declaration will be the (default) order of display.

Using these other keywords to declare participants will change the shape of the participant representation:

Syntax:

<participant_type> <label> as <alias>

Rename a participant using the as keyword.

You can also change the background color of actor or participant.

You can use the order keyword to customize the display order of participants.

Declaring participant on multiline

You can declare participant on multi-line.

[Ref. QA-15232]

Use non-letters in participants

You can use quotes to define participants. And you can use the as keyword to give an alias to those participants.

Message to Self

A participant can send a message to itself.

It is also possible to have multi-line using \n.

[Ref. QA-1361]

Text alignment

Text alignment on arrows can be set to left, right or center using skinparam sequenceMessageAlign.

You can also use direction or reverseDirection to align text depending on arrow direction. Further details and examples of this are available on the skinparam page.

Text of response message below the arrow

You can put the text of the response message below the arrow, with the skinparam responseMessageBelowArrow true command.

Change Actor style

You can change the actor style from stick man (by default) to:

Stick man (by default)

Awesome man

[Ref. QA-10493]

Hollow man

[Ref. PR#396]

Change arrow style

You can change arrow style by several ways:

Change arrow color

You can change the color of individual arrows using the following notation:

Message sequence numbering

The keyword autonumber is used to automatically add an incrementing number to messages.

You can specify a startnumber with autonumber <start> , and also an increment with autonumber <start> <increment>.

You can specify a format for your number by using between double-quote.

The formatting is done with the Java class DecimalFormat (0 means digit, # means digit and zero if absent).

You can use some html tag in the format.

You can also use autonumber stop and autonumber resume <increment> <format> to respectively pause and resume automatic numbering.

Your startnumber can also be a 2 or 3 digit sequence using a field delimiter such as ., ;, ,, : or a mix of these. For example: 1.1.1 or 1.1:1.

Automatically the last digit will increment.

To increment the first digit, use: autonumber inc A. To increment the second digit, use: autonumber inc B.

You can also use the value of autonumber with the %autonumber% variable:
[Ref. QA-7119]

Page Title, Header and Footer

The title keyword is used to add a title to the page.

Pages can display headers and footers using header and footer.

Splitting diagrams

With newpage

The newpage keyword is used to split a diagram into several images.

You can put a title for the new page just after the newpage keyword. This title overrides the previously specified title if any.

This is very handy with Word to print long diagram on several pages.

(Note: this really does work. Only the first page is shown below, but it is a display artifact.)

%page% and %lastpage% variables

[Ref. QA-6699]

Ignore newpage

You can use the ignore newpage command to show all the pages, as if there was no newpage.

Grouping message

It is possible to group messages together using the following keywords:

It is possible to add a text that will be displayed into the header (for group, see next paragraph 'Secondary group label').

The end keyword is used to close the group.

Note that it is possible to nest groups.

Secondary group label

For group, it is possible to add, between[ and ], a secondary text or label that will be displayed into the header.

[Ref. QA-2503]

Partition across the entire width

You can use partition command to group messages horizontally across the entire width (full-width).

Messages are not grouped horizontally across the entire width (by default)

Grouping messages horizontally across the entire width (with teoz mode)

[Ref. GH-589]

Notes on messages

It is possible to put notes on message using the note left or note right keywords just after the message.

You can have a multi-line note using the end note keywords.

Some other notes

It is also possible to place notes relative to participant with note left of , note right of or note over keywords.

It is possible to highlight a note by changing its background color.

You can also have a multi-line note using the end note keywords.

Changing notes shape [hnote, rnote]

You can use hnote and rnote keywords to change note shapes :

[Ref. QA-1765]

Note over all participants [across]

You can directly make a note over all participants, with the syntax:

[Ref. QA-9738]

Several notes aligned at the same level [/]

You can make several notes aligned at the same level, with the syntax /:

[Ref. QA-354]

Creole and HTML

It is also possible to use creole formatting:

Divider or separator

If you want, you can split a diagram using == separator to divide your diagram into logical steps.

Reference

You can use reference in a diagram, using the keyword ref over.

Delay

You can use ... to indicate a delay in the diagram. And it is also possible to put a message with this delay.

Text wrapping

To break long messages, you can manually add \n in your text.

Another option is to use maxMessageSize setting:

Message text spans beyond the involved participants

You can use sequenceMessageSpan command to allow message text to span beyond the involved participants.

Without sequenceMessageSpan (by default)

With sequenceMessageSpan (on teoz mode)

[Ref. GH-2386]

Space

You can use ||| to indicate some spacing in the diagram.

It is also possible to specify a number of pixel to be used.

Lifeline Activation and Destruction

The activate and deactivate are used to denote participant activation.

Once a participant is activated, its lifeline appears.

The activate and deactivate apply on the previous message.

The destroy denote the end of the lifeline of a participant.

Nested lifeline can be used, and it is possible to add a color on the lifeline.

Autoactivation is possible and works with the return keywords:

Return

Command return generates a return message with optional text label.

The return point is that which caused the most recent life-line activation.

The syntax is return label where label if provided is any string acceptable for conventional messages.

Participant creation

You can use the create keyword just before the first reception of a message to emphasize the fact that this message is actually creating this new object.

Shortcut syntax for activation, deactivation, creation

Immediately after specifying the target participant, the following syntax can be used:

Then you can mix activation and deactivation, on same line:

[Ref. QA-4834, QA-9573 and QA-13234]

Incoming and outgoing messages

You can use incoming or outgoing arrows if you want to focus on a part of the diagram.

Use square brackets to denote the left "[" or the right "]" side of the diagram.

You can also have the following syntax:

Short arrows for incoming and outgoing messages

You can have short arrows with using ?.

[Ref. QA-310]

Anchors and Duration

With teoz it is possible to add anchors to the diagram and use the anchors to specify duration time.

You can use the -P command-line option to specify the pragma:

java -jar plantuml.jar -Pteoz=true

[Ref. issue-582]

Stereotypes and Spots

It is possible to add stereotypes to participants using << and >>.

In the stereotype, you can add a spotted character in a colored circle using the syntax (X,color).

By default, the guillemet character is used to display the stereotype. You can change this behavious using the skinparam guillemet:

Position of the stereotypes

It is possible to define stereotypes position (top or bottom) with the command skinparam stereotypePosition.

Top postion (by default)

Bottom postion

[Ref. QA-18650]

More information on titles

You can use creole formatting in the title.

You can add newline using \n in the title description.
You can also define title on several lines using title and end title keywords.

Participants encompass

It is possible to draw a box around some participants, using box and end box commands.

You can add an optional title or a optional background color, after the box keyword.

It is also possible to nest boxes - to draw a box within a box - when using the teoz rendering engine, for example:

Removing Foot Boxes

You can use the hide footbox keywords to remove the foot boxes of the diagram.

Skinparam

You can use the skinparam command to change colors and fonts for the drawing.

You can use this command:

You can also change other rendering parameter, as seen in the following examples:

Changing padding

It is possible to tune some padding settings.

[Ref. QA-5493]

Appendix: Examples of all arrow type

Normal arrow

Itself arrow

Incoming and outgoing messages (with '[', ']')

Incoming messages (with '[')

Outgoing messages (with ']')

Short incoming and outgoing messages (with '?')

Short incoming (with '?')

Short outgoing (with '?')

Specific SkinParameter

By default

Style strictuml

To be conform to strict UML (for arrow style: emits triangle rather than sharp arrowheads), you can use:
[Ref. QA-1047]

LifelineStrategy

Since v1.2025.5, old skinparam lifelineStrategy solid no longer works. [Ref. QA-9016, QA-2794]

In order to have solid life line in sequence diagrams, you must now use style:
[Ref. GH-2266 and GH-2662]

Hide unlinked participant

By default, all participants are displayed.

But you can hide unlinked participant.

[Ref. QA-4247]

Color a group message

It is possible to color a group messages:

[Ref. QA-4750 and QA-6410]

Mainframe

[Ref. QA-4019 and Issue#148]

Slanted or odd arrows

You can use the (nn) option (before or after arrow) to make the arrows slanted, where nn is the number of shift pixels.

[Available only after v1.2022.6beta+]

[Ref. QA-14145]

[Ref. QA-6684]

[Ref. QA-1072]

Parallel messages (with teoz)

You can use the & teoz command to display parallel messages:

(See also Teoz architecture)

Style for Solid Lifeline

By default

Solid Lifeline using style

[Ref. GH-2266 and GH-2662]