Sequence Diagram Loop Alt and Opt Fragment Syntax Guide

If you've ever looked at a UML sequence diagram and wondered what those small boxed sections with labels like loop, alt, or opt mean, you're not alone. These are called combined fragments, and they're the syntax you need to model conditional logic, repetition, and optional behavior between objects. Without them, your diagrams can only show a single, straight-line interaction which rarely reflects how real software actually works.

This guide covers the exact syntax for loop, alt, and opt fragments in sequence diagrams. You'll learn what each one does, how to write them correctly in UML notation (including PlantUML syntax), and the mistakes that trip people up most often.

What Are Combined Fragments in a Sequence Diagram?

A combined fragment is a rectangular box drawn over one or more lifelines in a sequence diagram. It contains an interaction operator (like loop, alt, or opt) and one or more operands the regions inside the fragment that hold the actual messages.

Think of combined fragments as control flow statements for your diagram. They let you express things like:

"Repeat this exchange 3 times" → loop
"If condition A, do X; otherwise do Y" → alt
"Optionally do Z" → opt

The official UML specification defines 12 interaction operators, but loop, alt, and opt cover the vast majority of real-world modeling needs.

How Does the Loop Fragment Work?

The loop fragment repeats a set of messages a specified number of times, or until a condition becomes false. It has the following structure:

Operator: loop
Guard condition: Written in square brackets, placed in the top-left corner of the fragment. Typically includes a min/max iteration count or a boolean condition.
Operand: The messages that execute on each iteration.

Loop Fragment Syntax Example

Suppose a client sends a request to a server and retries up to 3 times if it fails. The fragment would look like this:

[loop, i=1..3]

Inside the fragment box, the client sends a request to the server. If the server responds with a failure, the loop continues. On success, it breaks out. In PlantUML, you'd write:

loop [i=1..3] Client -> Server : sendRequest Server --> Client : response end

You can also use a simple boolean guard like [retry needed] when the exact count doesn't matter.

When Should You Use a Loop Fragment?

Use loop whenever a sequence of interactions repeats. Common cases include:

Polling a service for status updates
Processing items in a batch or collection
Retrying failed operations
Iterating through records in a database

How Does the Alt Fragment Work?

The alt (alternative) fragment models mutually exclusive paths essentially an if/else statement. It divides the fragment into two or more operands separated by a dashed line. Each operand has its own guard condition in square brackets.

Alt Fragment Syntax Example

Consider a login scenario where the system checks credentials:

alt [valid credentials] Server --> Client : successResponse else [invalid credentials] Server --> Client : errorResponse end

Only one operand executes at runtime, based on which guard condition evaluates to true. The else keyword marks the default or fallback path. You can have more than two operands just chain additional conditions:

alt [role = admin] ... else [role = editor] ... else [role = viewer] ... end

When Should You Use an Alt Fragment?

Use alt whenever the flow splits based on a condition. Typical scenarios:

Success vs. failure responses from an API
Different paths based on user role or permissions
Branching business logic (approved vs. rejected)
Error handling with different recovery paths

You can read more about how messages work within these fragments in our lifeline and activation bar syntax guide.

How Does the Opt Fragment Work?

The opt (optional) fragment is simpler than alt. It has a single operand with one guard condition. The messages inside only execute if the condition is true. If false, they're skipped entirely.

Opt Fragment Syntax Example

Imagine a system that only sends a confirmation email when the user has opted in:

opt [user notifications enabled] System -> EmailService : sendConfirmation(to) end

That's it. There's no else branch. The opt fragment is the diagrammatic equivalent of a simple if statement with no else.

When Should You Use an Opt Fragment?

Optional feature flags or configuration toggles
Conditional notifications or logging
Steps that only apply under certain circumstances
Caching logic (fetch from cache only if available)

What's the Difference Between Alt and Opt?

This is a common point of confusion. Here's the short version:

opt = one path. It either happens or it doesn't. Like if (condition) { ... }
alt = two or more paths. Exactly one executes. Like if (a) { ... } else { ... }

If you only need to model an optional step with no alternative, use opt. The moment you need an "otherwise," switch to alt.

A useful rule of thumb: an opt fragment can always be rewritten as an alt fragment where the second operand is empty. But using opt communicates your intent more clearly and keeps the diagram cleaner.

What Are Common Mistakes When Drawing These Fragments?

1. Missing or Confusing Guard Conditions

Every operand needs a guard condition in square brackets. Without it, readers can't tell when that path executes. Write guards that are specific and testable [payment successful] is better than [ok].

2. Using Loop When You Mean Alt

Some modelers use a loop fragment when they actually want conditional branching. If the behavior doesn't repeat, don't use loop. Check the interaction operator it should match the control flow you're modeling.

3. Forgetting the Else Keyword in Alt Fragments

Each operand after the first in an alt fragment should be preceded by else (or another condition keyword). Without it, the diagram is ambiguous readers won't know if the operands are alternatives or something else entirely.

4. Overlapping Fragments on Different Lifelines

Fragments should span the lifelines involved in the messages they contain. If a message between Client and Server is inside a fragment, that fragment's box should cover both those lifelines. Don't leave a lifeline partially inside and partially outside the fragment boundary.

5. Nesting Fragments Without Clear Visual Separation

You can nest an opt fragment inside an alt fragment (or a loop inside a loop), but make sure the boxes are visually distinct. Nested fragments should be clearly smaller and offset so readers can see the hierarchy. In tools like PlantUML, this is handled automatically when you nest the syntax correctly.

How Do You Write These Fragments in PlantUML?

PlantUML uses a straightforward text-based syntax for combined fragments. Here's a quick reference:

Loop:

loop [condition] A -> B : message end

Alt:

alt [condition1] A -> B : message else [condition2] A -> B : otherMessage end

Opt:

opt [condition] A -> B : message end

You can nest these freely, combine them with break and continue operators, and reference them in notes. For the full syntax details, see our PlantUML sequence diagram syntax reference.

Practical Tips for Using Fragments Well

Keep guard conditions short and readable. One line is ideal. If you need a long explanation, add a note attached to the fragment instead.
Use alt for error handling patterns. It maps naturally to try/catch or success/failure flows that developers already understand.
Limit nesting to two or three levels deep. Beyond that, the diagram becomes hard to read. Consider breaking it into separate diagrams or using ref fragments to call sub-diagrams.
Label your fragments consistently across a project. If your team uses [success] and [failure] for alt guards, don't switch to [ok] and [error] in another diagram.
Use the combined fragment interaction operator glossary in the full fragment syntax guide if you need operators beyond loop, alt, and opt (like par, break, or critical).

Quick Reference: Loop vs. Alt vs. Opt

loop Repeats messages. Use for iteration, polling, retries. Requires a guard with optional iteration bounds.
alt Branches into mutually exclusive paths. Use for if/else logic. Requires guards on every operand and else keywords after the first.
opt Executes optionally. Use for conditional steps with no alternative. Requires one guard on the single operand.

Next Steps

Pick one real feature or flow in your current project and model it as a sequence diagram with at least one alt or loop fragment.
Write the diagram in PlantUML text syntax so it's versionable and easy to update.
Review the guards make sure each one is a clear, testable condition that a developer or stakeholder would understand without guessing.
Share the diagram with a teammate and ask if the control flow is obvious. If they hesitate, simplify or add notes.