# xsl:for-each-group

The `xsl:for-each-group` element selects a sequence of nodes and/or atomic values and organizes them into subsets called groups. There are four possible ways of defining the grouping:

- group-by: This groups together all items having the same value for a grouping key. The grouping key may have multiple values (a sequence of values) in which case the item is added to more than one group.

- group-adjacent: This groups together all items having the same value for a grouping key, provided that they are also adjacent in the input sequence. This is useful when you need to wrap a new element around a sequence of related elements in the source documents, for example a consecutive sequence of `<bullet>` elements. In this case the grouping key must be single-valued.

- group-starting-with: This processes the items in the supplied sequence in turn, starting a new group whenever one of the items matches a specified pattern. This is useful, for example, when matching an `<h2>` element and its following `<p>` elements.

- group-ending-with: This processes the items in the supplied sequence in turn, closing the current group whenever one of the items matches a specified pattern. This is useful when matching a sequence of items in which the last item in the group carries some distinguishing attribute such as `continued="no"`.

Saxon implements the `xsl:for-each-group` instruction in full, except that some error conditions are not detected. For examples of using the instruction, see the draft XSLT 2.0 specification.

Expand | Next