Lifelines
Lifelines are the basic building block for sequence diagrams. They represent the participants that send and receive messages in sequence diagrams. The lifeline consists of a head with a name and a line drawn vertically down from the head. The default head is a rectangle with a name in it. PlantUML draws a foot as well. The foot is nice aesthetically but is not an official part of UML. We will leave it in our examples for aesthetic reasons.
Declaration
Use the "participant" keyword followed by a name to declare a default lifeline. Lifelines automatically appear left to right in order of declaration.
Example: Declaring Lifelines
@startuml
'Example: Declaring Lifelines
'Declare default lifelines and name them.
participant Sean
participant Maria
participant Zarek
@enduml
Properties
Properties following the participant_type affect the format of the lifeline head. To declare a lifeline, you must only use the participant_type and name properties. There is some wiggle room with the property order. For the sake of consistency and best practice, we will keep them in the below order throughout this book. Below is a list of lifeline properties.
participant_type - determines the head shape based on its classifier
name - the text that appears in the head of the lifeline
display_name - a method for formatting name, comes after name
formatted_name - used in place of name and display_name
variable_name - used as a variable for a lifeline with a long name
back_ground_color - sets the background color of the head
stereotype - allows for the head to display a stereotype
order_number - adjusts the horizontal order of lifelines
Participant Type
There are several options for participant_type. Replace participant with any other participant_type. The options are indicative of UML classifiers. PlantUML will change the header shape accordingly. Below is a list of participant types.
participant
actor
boundary
control
entity
database
collections
queue
Example: Participant Type
@startuml
'Example: Participant Type
'Declare lifelines with different head shapes.
participant participant
actor actor
boundary boundary
control control
entity entity
database database
collections collections
queue queue
@enduml
Name
The name is simply text that appears in the head of the lifeline. The name can be a single word without quotation marks or it can be a string with quotation marks. The string method supports line breaks.
Example: Name
@startuml
'Example: Name
'Declare a lifeline with a simple name
participant Sean
'Declare a lifeline with a name as a string
participant "Maria The Closer"
'Declare a lifleine with a multiline name
participant "Zarek \nThe Guy With \nCurly Hair"
@enduml
Display Name
The display_name property follows the "as" keyword. It can be used to display text in the head that is entirely different from the name. The display_name property supports creole syntax for emphasis and markup language for color. You can define colors with a standard color name or hex code. Oddly PlantUML does not support emphasis with markup in the lifeline head. This lack of markup options does not align with all PlantUML text fields. Luckily, we can combine markup and creole. See Text Formatting for a list of creole and markup options.
Example: Display Name
@startuml
'Example: Display Name
'Declare a lifeline with bold text using creole.
participant Sean as "**Juanito**"
'Declare a lifeline with purple text using markup.
participant Maria as "<color:#561D5E>Mija Mia</color>"
'Declare a lifeline with bold red text using markup and creole.
participant Zarek as "<color:#FF0000>**Zarek**</color>"
@enduml
Formatted Name
The formatted_name property replaces name and display_name. Similar to display_name it supports creole syntax for emphasis and markup language for color. You can define colors with a standard color name or hex code. Once again, PlantUML does not support emphasis with markup in the lifeline head. However, we can still combine markup and creole. See Text Formatting for a list of creole and markup options.
Example: Formatted Name
@startuml
'Example: Formatted Name
'Declare a lifeline with bold text using creole.
participant "**Juanito**"
'Declare a lifeline with purple text using markup.
participant "<color:#561D5E>Mija Mia</color>"
'Declare a lifeline with bold red text using markup and creole.
participant "<color:#FF0000>**Zarek**</color>"
@enduml
Variable Name
A variable_name is just that, a variable. You can assign a lifeline to a variable using the "as" keyword. This practice eases utilization of a lifeline with a formatted_name. Otherwise, you have to type the entire lifeline name, including formatting, every time you use that lifeline. To show this we will pass a few messages between our lifelines. Messages will not be explained here. See the messages section for an in-depth explanation.
Example: Variable Name
@startuml
'Example: Variable Name
'Declare lifeline Sean with a formatted_name and a variable_name.
participant "**Juanito**" as Sean
'Declare lifeline Mija Mia with a formatted_name only.
participant "<color:#561D5E>Mija Mia</color>"
'Declare lifeline Zarek with a formatted_name and a variable_name.
participant "<color:#FF0000>**Zarek**</color>" as Zarek
'Send a message from Sean to Mia. It's fairly ugly and will quickly become cumbersome.
Sean -> "<color:#561D5E>Mija Mia</color>"
'Send a message from Juanito to Zarek.
Sean -> Zarek
@enduml
Background Color
The background_color property allows you to change the background color of the lifeline head. You can define colors with a standard color name or hex code. Create a gradient by using two colors. Notice that these colors can be used on any participant_type.
Example: Background Color
@startuml
'Example: Background Color
'Declare lifeline Sean with a cyan background_color.
participant Sean #Cyan
'Declare lifeline Zarek with a red background_color.
actor Zarek #FF0000
'Declare lifeline Maria with a purple to black gradient background_color.
'Changes Maria's text color to white.
queue Maria as "<color:#White>Mia</color>" #561D5E/000000
@enduml
Stereotype
The stereotype property gives the ability to add a stereotype to the lifeline head. You can emphasize stereotype text with creole syntax and color it with markup. It is also possible to embed a colored circle with an internal character or both. Define colors with a standard color name or hex code.
Example: Stereotype
@startuml
'Example: Stereotype
'Declare a participant with a cyan colored spot with a lower case Y in the spot.
participant Sean << (y,#00FFFF) >>
'Declare a participant with a stereotype that is bold and purple.
participant Maria << <color:#561D5E>**Middle Child**</color> >>
'Declare a participant with a red colored spot with a capital letter O in it
'Make it also have a stereotype
participant Zarek << (O,#FF0000) The Oldest >>
@enduml
Order Number
The order_number property allows you to arrange lifelines regardless of their order in the code.
Example: Order Number
@startuml
'Example: Order Number
'Declare this lifeline first, but make it appear second.
participant "Maria the middle child" order 2
'Make this lifeline appear last.
participant "Sean the youngest" order 3
'Make this lifeline appear first.
participant "Zarek the oldest" order 1
@enduml
Undeclared Lifelines
You can create a sequence diagram without declaring lifelines. However, the lifelines will only have default properties. Lifelines are automatically generated as they appear in messages. This can be useful if you assemble a quick sequence diagram without bells or whistles.
Example: Undeclared Lifelines
@startuml
'Example: Undeclared Lifelines
'Send some messages without declaring any lifelines.
Sean -> Maria : Text
Sean <-- Maria : Text
Maria -> Zarek : Text
Maria <-- Zarek : Text
Zarek -> Sean : Text
Zarek <-- Sean : Text
@enduml
Participants Creating New Lifelines
A participant can create another participant, therefore starting a new lifeline. The creation commands are below.
create - creates a lifeline on the following message line
** - shortcut for create that is used on the message line
Use the create command on the line before the creation message. Use the ** shortcut command immediately following the name of the created lifeline in the message line. To comply with UML standards, be sure to draw the creation message with a dashed line and an open arrowhead. See lines 11 and 16 below. Messages are thoroughly covered in the messages section.
The new lifeline will not visually exist in the sequence diagram until created. However, if you want to adjust the new lifeline properties, you must declare the lifeline beforehand. Undeclared lifelines that are created with the create command have default properties just like the undeclared lifelines example above.
Example: Participants Creating New Lifelines
@startuml
'Example: Participants Creating New Lifelines
participant Sean
'Declare Maria as an actor with a purple background.
actor Maria #561D5E
'Make Sean create Maria.
create Maria
Sean -->> Maria: Creation Message
Sean -> Maria: Text
'Make Maria create Zarek.
'Use the shortcut method.
Maria -->> Zarek **: Creation Message
Maria -> Zarek: Text
Zarek --> Maria: Text
Maria --> Sean : Text
@enduml
Visibility
It is possible to hide the lifeline foot. It is also possible to hide lifelines that do not send or receive messages. You can do both the following hide commands.
hide footbox - hides the lifeline foot from the sequence diagram drawing
hide unlinked - hides all inactive lifelines
Example: Lifeline Visibility
@startuml
'Example: Lifeline Visibility
'Remove the lifeline feet.
hide footbox
'Hide inactive lifelines.
hide unlinked
'Declare three lifelines.
participant Maria
participant Sean
participant Zarek
'Send messages between only two lifelines.
Maria -> Sean : Text
Maria <- Sean : Text
@enduml
Last updated
Was this helpful?