When you're modeling how objects communicate over time, plain message arrows only tell part of the story. Real software has conditions, loops, parallel processing, and exceptions. That's where combined fragments come in they're the box-with-dashed-border constructs in UML sequence diagrams that capture this logic. If your diagrams skip them, you're leaving out the behavior that actually matters to developers and reviewers. Let's look at how combined fragments work, with real examples you can apply right away.

What exactly is a combined fragment in a sequence diagram?

A combined fragment is a rectangular frame drawn with a dashed border on a sequence diagram. It groups one or more interaction fragments meaning a set of messages and lifelines under a specific interaction operator. The operator keyword (like alt, opt, or loop) appears in a small label in the top-left corner of the frame. A guard condition in square brackets controls when that fragment runs.

You can find the full notation details in our UML sequence diagram notation reference.

Think of a combined fragment as a way to say: "These messages happen together, but only under certain conditions, or in a certain pattern." Without it, your diagram would look like a single linear flow, which almost never reflects real software behavior.

What does the alt combined fragment do?

alt stands for "alternative." It works like an if/else block. The fragment is divided into two or more regions separated by a dashed horizontal line. Each region has a guard condition. Only one region executes, based on which condition is true.

Example scenario: A payment service calls an authorization gateway. If authorization succeeds, it sends a confirmation. If it fails, it sends an error message back to the client.

  • Region 1 guard: [authorization successful] → Send confirmation message to Customer
  • Region 2 guard: [authorization failed] → Send error message to Customer

This is the most common combined fragment you'll encounter. Nearly every system with branching logic needs one.

How is opt different from alt?

The opt (optional) fragment has only one region. It executes when the guard condition is true and does nothing otherwise. You could model this with alt by leaving the else region empty, but opt communicates the intent more clearly: something might happen, or it might not.

Example: When a user logs in, the system optionally sends a push notification if the user has notifications enabled.

  • opt [user.notificationsEnabled] → Send push notification to User's device

When do you use a loop combined fragment?

The loop fragment repeats a set of messages. You write the guard condition to describe when the loop continues or stops. You can also specify a minimum and maximum iteration count in the fragment header, like loop (1, 10).

Example: A batch processor retrieves records from a database in pages. Each iteration fetches the next page until no more records are available.

  • loop [hasMoreRecords] → BatchProcessor sends "fetchNextPage" to Database → Database returns results

If you need to express this in code form, our PlantUML sequence diagram syntax reference shows how to write the loop operator with proper guard syntax.

What about par for parallel execution?

The par (parallel) fragment contains multiple regions that execute simultaneously. Each region is separated by a dashed line, and all regions run at the same time rather than sequentially.

Example: When an order is placed, the system simultaneously charges the payment provider and reserves inventory in the warehouse.

  • Region 1: OrderService → PaymentGateway: chargeCard()
  • Region 2: OrderService → InventoryService: reserveItems()

This is especially useful for modeling event-driven and microservice architectures where concurrent operations are the norm.

Which combined fragments do developers use most often?

Based on real-world modeling practice, here's a rough frequency ranking:

  1. alt if/else branching (most common by far)
  2. loop repetition and iteration
  3. opt optional execution
  4. par concurrent messages
  5. break interrupting a loop or flow early
  6. critical atomic, non-interruptible region
  7. assert asserting a condition must hold
  8. neg showing a sequence that must NOT happen
  9. ref referencing a separate interaction fragment

You'll use alt, loop, and opt in almost every non-trivial diagram. The others appear when you need to model concurrency, error handling, or formal constraints.

Can you nest combined fragments inside each other?

Yes, and this is where things get powerful. You can place a combined fragment inside another one. For example, inside a loop that iterates over records, you might have an alt fragment that branches on whether each record is valid.

  • loop [hasMoreRecords]
    • Fetch record
    • alt [record.isValid] → Process record
    • alt [else] → Log warning, skip record

Nesting captures real logic faithfully, but be careful not to go more than two or three levels deep. Deeply nested fragments make diagrams hard to read. If you find yourself stacking four or more layers, consider breaking the logic into a separate referenced interaction using a ref fragment.

What mistakes do people make with combined fragments?

Here are the errors I see most frequently in sequence diagrams:

  • Forgetting the guard condition. A combined fragment without a guard in square brackets is incomplete. The reader doesn't know why that path executes. Always write the guard.
  • Using alt when opt is clearer. If one branch has no else behavior, use opt instead of an alt with an empty second region.
  • Drawing the frame border as solid. Combined fragments use dashed lines. Solid lines are for reference frames and interaction uses, which are different constructs.
  • Overloading one diagram. If you have more than three or four combined fragments on a single diagram, it's probably time to split the scenario into separate diagrams or use ref fragments.
  • Ignoring the interaction constraint syntax. UML defines a specific constraint language (UML OCL or natural language). Don't just slap in ambiguous text like "sometimes" or "maybe."
  • Mixing up par with loop. par means simultaneous. loop means repeated sequentially. These model fundamentally different behaviors.

How do you write combined fragments in diagramming tools?

Most tools that support sequence diagrams also support combined fragments. In Mermaid.js, the sequence diagram syntax covers alt, opt, loop, and par blocks. PlantUML offers even more operators including break, critical, and ref.

If you're using a visual editor like Draw.io, Lucidchart, or Enterprise Architect, look for the "combined fragment" tool in the sequence diagram shape library. You'll typically drag a dashed-border rectangle onto the diagram, select the operator from a dropdown, and type the guard condition.

Practical checklist for using combined fragments

  • ☐ Identify every conditional branch in your scenario → use alt
  • ☐ Identify every optional step → use opt
  • ☐ Identify every repeating action → use loop
  • ☐ Identify every concurrent set of messages → use par
  • ☐ Write a clear, concise guard condition for each region
  • ☐ Keep nesting to two levels maximum for readability
  • ☐ Use ref to break out complex sub-flows into separate diagrams
  • ☐ Use dashed borders (not solid) for all combined fragment frames
  • ☐ Review with your team sequence diagrams are communication tools, not just documentation

Start with one real user scenario from your system. Map the happy path first. Then add alt, opt, and loop fragments for the branching, optional, and repeated behavior. You'll have a useful, readable diagram within 15 minutes.