XSLT Reference

xsl:iterate

XSLT 3.0 element

Processes a sequence item-by-item with carry-forward parameters, enabling efficient streaming and stateful iteration in XSLT 3.0.

Syntax

<xsl:iterate select="sequence">

Description

xsl:iterate is an XSLT 3.0 instruction that processes a sequence one item at a time, similar to xsl:for-each, but with two important additions:

Carry-forward parameters — declared with xsl:param inside the instruction, updated at the end of each iteration via xsl:next-iteration, and available in the final result via xsl:on-completion.
Early termination — xsl:break stops iteration before the end of the sequence, optionally emitting output at that point.

These features make xsl:iterate the right tool for running aggregations (cumulative totals, maximums, etc.), building state across items, or stopping as soon as a condition is met. It also works in streaming mode (xsl:stream) because it processes the sequence without needing to hold it all in memory simultaneously.

Parameters

Parameter	Type	Required	Description
`select`	XPath expression	Yes	The sequence to iterate over.

Child elements

Element	Description
`xsl:param`	Declares a carry-forward parameter with an initial value.
`xsl:next-iteration`	Provides updated parameter values for the next iteration. Must be the last instruction in the body (or inside `xsl:break`).
`xsl:on-completion`	Body executed after the last item (or after `xsl:break`). Has access to the final carry-forward parameter values.
`xsl:break`	Terminates the iteration immediately; can contain `xsl:on-completion` inline.

Return value

The instruction produces the nodes/items written by its body instructions and by xsl:on-completion.

Examples

Running total

Input XML:

<?xml version="1.0" encoding="UTF-8"?>
<orders>
  <order amount="120.00"/>
  <order amount="45.50"/>
  <order amount="200.00"/>
  <order amount="33.25"/>
</orders>

Stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="/orders">
    <xsl:iterate select="order">
      <xsl:param name="total" as="xs:decimal" select="0"/>
      <xsl:next-iteration>
        <xsl:with-param name="total" select="$total + xs:decimal(@amount)"/>
      </xsl:next-iteration>
      <xsl:on-completion>
        <summary>
          <total><xsl:value-of select="$total"/></total>
        </summary>
      </xsl:on-completion>
    </xsl:iterate>
  </xsl:template>
</xsl:stylesheet>

Output:

<summary>
  <total>398.75</total>
</summary>

Stop at first match

Stylesheet (find the first order over 100):

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="/orders">
    <xsl:iterate select="order">
      <xsl:choose>
        <xsl:when test="xs:decimal(@amount) gt 100">
          <xsl:break>
            <first-large-order amount="{@amount}"/>
          </xsl:break>
        </xsl:when>
      </xsl:choose>
    </xsl:iterate>
  </xsl:template>
</xsl:stylesheet>