If you've ever stared at a sequence diagram and wondered what those rectangular boxes with "loop" labels mean or you're trying to create one yourself and the syntax feels confusing you're not alone. The loop fragment is one of the most commonly used combined fragments in UML sequence diagrams, and understanding its syntax is essential for accurately modeling repetitive behavior in software interactions. Getting it wrong can lead to diagrams that misrepresent how your system actually works, which causes confusion during design reviews and handoffs.

What is a loop fragment in a sequence diagram?

A loop fragment is a type of combined fragment in UML sequence diagrams that represents a repeated sequence of messages. It tells the reader: "these interactions happen more than once, under certain conditions." Think of it as the visual equivalent of a while loop or a for loop in code.

The loop fragment appears as a rectangular region on the diagram with a small label in the top-left corner that reads "loop". Inside that box, you'll find the lifelines and messages that repeat. The condition or iteration bounds are written in the fragment's header, usually in square brackets.

For a broader understanding of all the symbols used in these diagrams, our guide on UML sequence diagram symbols and their meanings covers the full picture.

How do you write loop fragment syntax?

The general syntax for a loop fragment header looks like this:

loop [condition]

Or with explicit iteration bounds:

loop [min, max]

Here's what those parts mean:

• condition A Boolean expression that determines whether the loop continues (similar to a while-loop condition).
• min The minimum number of times the loop body executes.
• max The maximum number of times the loop body executes.

For example:

• loop [for each item in cart] Iterates over every item in a shopping cart.
• loop [count < 3] Repeats while a counter is less than three.
• loop [1, 10] Executes at least once and at most ten times.
• loop [0, ] Executes zero or more times (the means unlimited).

What does a practical loop fragment example look like?

Imagine a user checking out on an e-commerce site. The system needs to process each item in the cart before finalizing the order. Here's how that interaction would look with loop fragment notation:

1. The User lifeline sends a "checkout" message to the OrderService lifeline.
2. A loop fragment wraps around the interaction between OrderService and InventoryService.
3. The loop header reads: loop [for each cart item]
4. Inside the loop, OrderService sends "checkStock(item)" to InventoryService, and InventoryService returns a stock status.
5. After the loop completes, OrderService sends "confirmOrder" to the User.

This tells any reader of the diagram that stock checking is a repeated step once per item before the order is confirmed. It's much clearer than drawing the same message arrow multiple times.

If you want to see how this translates into actual diagram code, our PlantUML sequence diagram code examples walk through real implementations line by line.

What's the difference between a loop fragment and an alt or opt fragment?

People sometimes confuse loop fragments with other combined fragments. Here's a quick comparison:

• loop Repeats a sequence of messages multiple times based on a condition or iteration count.
• alt Represents an if/else choice between two or more paths (only one path executes).
• opt Represents an optional path that either executes once or not at all (like an if without an else).
• break Exits the enclosing loop fragment early when a condition is met.

A break fragment is nested inside a loop fragment. When the break condition is true, the loop stops immediately and control moves past the loop. This mirrors the break statement in most programming languages.

Our resource on how to write sequence diagram notation covers these other fragment types in more detail if you need a refresher.

Common mistakes when using loop fragments

Here are errors that show up frequently in sequence diagrams involving loop fragments:

• Missing the condition or bounds. A loop fragment without a header condition leaves readers guessing about how many times the interaction repeats. Always include either a condition or iteration bounds.
• Placing lifelines incorrectly. Only lifelines that participate in the repeated interaction should be inside the loop fragment box. Dragging unrelated lifelines into the fragment makes the diagram cluttered and misleading.
• Confusing loop with recursion. A loop fragment shows repeated messages between two or more objects. A self-call (where a lifeline sends a message to itself) represents recursion. These are different concepts. Don't use a loop fragment to model a recursive call.
• Using vague conditions. Writing loop [condition] without replacing "condition" with an actual expression defeats the purpose. Be specific, like loop [retries < 3] or loop [for each row].
• Forgetting the return message. If the loop body includes a request-response pattern, make sure the response message is also inside the loop fragment. Leaving it outside changes the meaning entirely.

Tips for writing clear loop fragments

• Use natural language conditions when the audience is non-technical. Writing loop [for each user in the list] is often more readable for business stakeholders than a formal Boolean expression.
• Show one full iteration clearly. Don't try to draw every repetition visually. The loop fragment label communicates repetition. Draw one complete cycle with all the messages inside the fragment, and let the label do the rest.
• Nest fragments carefully. A loop can contain an alt or opt fragment inside it. For example, inside a retry loop, you might have an alt that shows success and failure paths. Keep nesting to two levels max to preserve readability.
• Use consistent notation across your team. If your team uses PlantUML or another tool, agree on conventions for loop labels. The official UML specification from the Object Management Group (OMG) defines these fragments formally, but teams often adopt shorthand.
• Label the loop with a meaningful keyword. Instead of generic text, use domain-specific language that communicates intent. loop [retry failed payment] is more informative than loop [condition].

Quick checklist before you share your diagram

1. Does every loop fragment have a clear condition or iteration bound in the header?
2. Are only the relevant lifelines enclosed inside the loop box?
3. Is the return/response message inside the loop (not outside)?
4. Can someone unfamiliar with your system understand what repeats and why?
5. Have you distinguished between loop (repetition) and alt/opt (conditional branching)?
6. If you used a break fragment inside the loop, is the exit condition clear?
7. Did you avoid nesting more than two combined fragments deep?

Start by sketching your loop fragment on paper or a whiteboard before using a diagramming tool. Write the condition first, then place the messages, then draw the fragment box around them. This order prevents the common mistake of drawing the box first and then struggling to fit the content cleanly inside it.