Uml Sequence Diagram Example: Conditional Branching (alt/opt)

When you model software behavior, not everything follows a straight line. Login requests get rejected. Payments fail. Users pick different options from a menu. If your sequence diagrams only show the happy path, they miss what actually happens in production. That's where a UML sequence diagram with conditional branching becomes essential it lets you show exactly how your system responds when things go off the expected path.

What is conditional branching in a UML sequence diagram?

Conditional branching (also called alternative fragments or alt fragments) is a way to show two or more possible paths in a sequence diagram based on a condition. The UML notation uses a rectangular box called a combined fragment with the operator alt to represent this. Inside the box, you divide the interaction into sections separated by a dashed line one section for each possible outcome.

Think of it like an if/else statement in code. One path runs when the condition is true, and the other runs when it's false. Each section has a guard condition written in square brackets that describes when that path executes.

For a full breakdown of the notation rules, you can check this sequence diagram syntax guide.

Why should I model conditional branches instead of just showing the main flow?

Because the main flow is rarely the only flow. If you're designing an authentication system, a payment module, or any feature where outcomes differ, your team needs to see what happens in every case. Without conditional branches, developers guess and they often guess differently from each other.

Conditional branching in sequence diagrams helps with:

Code reviews: Reviewers can verify that every branch is handled before implementation.
Testing: QA teams can derive test cases directly from each guarded path.
Communication: Non-technical stakeholders understand decision points without reading code.
Bug prevention: Missing branches become visually obvious on the diagram.

How do I draw a conditional branch in a sequence diagram?

Here's the basic structure:

Draw a rectangular box (combined fragment) that spans the lifelines involved.
Label the top-left corner with alt.
Write the guard condition in brackets for the first path, like [login successful].
Show the messages that occur on that path.
Draw a dashed horizontal line to separate the next section.
Write the alternative guard condition, like [login failed].
Show the messages for that alternative path.

You can also reference the PlantUML notation reference if you're using PlantUML to generate your diagrams from text.

What does a real example look like?

Let's take a user login scenario. A User sends a login request to an Authentication Service. The service checks credentials against a database. If credentials are valid, the system returns a success response with a token. If not, it returns an error message.

In a sequence diagram with conditional branching, this looks like:

The User actor sends login(username, password) to the Authentication Service.
The Authentication Service sends validateCredentials() to the Database.
The combined fragment (alt) starts here, spanning the Authentication Service and User lifelines.
Section 1 [credentials valid]: The Database returns true. The Authentication Service sends generateToken() to the Token Service, receives the token, and sends loginSuccess(token) back to the User.
Dashed separator line.
Section 2 [credentials invalid]: The Database returns false. The Authentication Service sends loginFailed("Invalid credentials") back to the User.

This pattern appears in countless systems. You might also see nested alt fragments when a single interaction has multiple decision points, like checking account status after successful authentication.

What other combined fragments work alongside alt?

The alt fragment is the most common, but UML defines several combined fragments that often appear together:

opt An optional fragment. The interaction inside only happens if the condition is true. It's like an if without an else.
loop Repeats the interaction a set number of times or while a condition holds.
break Exits the enclosing fragment if the condition is met.
par Shows parallel execution of multiple interaction fragments.
critical Marks a section that must complete without interruption.

You can mix these with alt to model complex behaviors. For example, a loop with an alt inside it models retry logic with different outcomes on each attempt.

What common mistakes do people make with conditional branches?

Several patterns come up again and again:

Missing the else branch. Every alt fragment should have at least two sections. If you only show one path, use opt instead.
Vague guard conditions. Writing [success] or [failure] isn't specific enough. Use conditions tied to actual system state, like [user.role == "admin"] or [response.status == 200].
Scope errors. The alt box should only span the lifelines involved in the decision. Don't wrap lifelines that aren't part of the branch.
Too many branches in one fragment. If your alt has five or six sections, the diagram becomes hard to read. Consider breaking it into smaller interactions or using sub-diagrams.
Forgetting message return values. The condition that triggers a branch often depends on a return value from a previous message. Make sure that message and its response are clearly shown before the alt fragment starts.

How do I write conditional branches in PlantUML or other tools?

In PlantUML, you write alt fragments using a straightforward text syntax. You start with alt description, list the messages for that path, then use else to separate alternative paths, and close with end. Guard conditions go in square brackets next to the alt or else keyword.

Most tools including Mermaid, Lucidchart, and draw.io support alt fragments through their GUI or text-based interfaces. The visual output varies slightly, but the underlying UML semantics stay the same.

If you want a deeper look at the syntax rules for sequence diagrams in general, the conditional branching examples on this site walk through several patterns step by step.

When would I use branching versus separate diagrams?

Use branching (alt fragments) when:

The alternatives are closely related and happen within the same interaction.
You want to show decision logic in context readers can see both paths side by side.
The total number of branches is small (two or three).

Use separate diagrams when:

Each branch involves a long, complex sequence of messages.
You have four or more distinct outcomes.
Each branch warrants its own narrative or documentation section.
Nesting becomes so deep the diagram is unreadable.

The goal is always clarity. If combining branches into one diagram makes it harder to understand, split them out.

Can I combine conditional branching with loops?

Yes, and it's a very common pattern. Imagine a retry mechanism: the system tries a payment, and if it fails, it retries up to three times. Each attempt might have its own success or failure outcome.

In this case, you'd place a loop fragment around the alt fragment or nest the alt inside the loop, depending on the exact behavior you're modeling. The loop guard condition describes the retry logic ([attempts < 3]), and the alt guard describes the outcome of each attempt.

Be careful with nesting depth. Two levels of combined fragments are usually fine. Three levels start to get confusing. At that point, consider splitting the diagram.

Practical checklist for your next sequence diagram with conditional branching

✅ Identify every decision point in the interaction before you start drawing.
✅ Write specific guard conditions avoid vague terms like "success" or "error."
✅ Include both (or all) branches. Don't leave out the failure case.
✅ Scope the alt box to only the lifelines involved in the decision.
✅ Keep nesting to two levels or fewer. Split complex branches into separate diagrams if needed.
✅ Make sure the triggering message and its response are visible before the alt fragment.
✅ Review the diagram with at least one developer and one tester to confirm branch coverage.
✅ Use your diagram as a basis for test cases each guard condition maps to at least one test.

Start by mapping your decision points on paper or a whiteboard. Once you're clear on the branches, translate them into your diagramming tool of choice. If you're working in text-based tools like PlantUML, keep a library of reusable alt fragment templates to speed up your workflow.