XSLT template matching explained with examples

Template matching is the mechanism that drives every XSLT transformation. Understanding how the processor selects templates — and what happens when multiple templates could match — is the difference between a stylesheet that works reliably and one that produces surprising output. This post covers everything you need to know.

How match patterns work

When the processor visits a node, it evaluates every template’s match attribute as an XPath pattern. A pattern is a restricted form of XPath that tests properties of a node rather than selecting nodes from a starting point. If the pattern is satisfied, that template is a candidate.

<xsl:template match="book">        <!-- matches any book element -->
<xsl:template match="catalog/book"> <!-- matches book that is a child of catalog -->
<xsl:template match="book[@id]">   <!-- matches book elements with an id attribute -->
<xsl:template match="*">           <!-- matches any element -->
<xsl:template match="text()">      <!-- matches any text node -->
<xsl:template match="@*">          <!-- matches any attribute -->

Priority and conflict resolution

More than one template can match the same node. The processor resolves the conflict using priority. Each pattern has a default priority calculated by the spec:

More specific patterns automatically get higher priority. You can override this with the priority attribute:

<xsl:template match="book" priority="1">
  <!-- this wins over a match="book" template at default priority -->
</xsl:template>

If two templates have equal computed priority, the processor signals an error (or picks the last one, depending on implementation — Saxon issues an error by default). Always assign explicit priorities when you have competing templates.

The built-in templates

XSLT has default templates for every node type. If no explicit template matches a node, the built-in fires. For elements and the document root, the built-in calls apply-templates on all children. For text and attribute nodes, it outputs the string value.

This means that without any templates at all, the processor will walk the entire tree and output all text content. Understanding this explains why simple stylesheets can produce unexpected extra text — a text node matched nothing explicit, and the built-in output it.

To suppress text output globally, add:

<xsl:template match="text()"/>

This overrides the built-in with an empty template, producing no output for text nodes that are not handled elsewhere.

Modes

Modes let you have multiple templates for the same node that serve different purposes. A mode is a named context for a set of templates.

<!-- Default mode: output a summary row -->
<xsl:template match="book">
  <tr><td><xsl:value-of select="title"/></td></tr>
</xsl:template>

<!-- detail mode: output a full card -->
<xsl:template match="book" mode="detail">
  <div class="card">
    <h2><xsl:value-of select="title"/></h2>
    <p><xsl:value-of select="description"/></p>
  </div>
</xsl:template>

Call with mode:

<xsl:apply-templates select="catalog/book" mode="detail"/>

Modes are especially useful when you need to process the same nodes in multiple places in the output with different logic each time.

apply-templates vs for-each

Both iterate over a set of nodes. The difference is that apply-templates dispatches to the best matching template for each node, while for-each stays in the current context and does not do template lookup.

Use apply-templates when you want polymorphism — different node types handled differently. Use for-each when you are doing a simple iteration over a homogeneous set and do not need dispatch.

<!-- apply-templates: each node can match a different template -->
<xsl:apply-templates select="items/*"/>

<!-- for-each: all items handled inline -->
<xsl:for-each select="items/item">
  <li><xsl:value-of select="."/></li>
</xsl:for-each>

Testing patterns in XSLT Playground

XSLT Playground is a fast way to experiment with matching rules. Paste a stylesheet with multiple competing templates and check which one fires. Add <xsl:message select="name()"/> in each template to trace which one the processor picks. The trace panel shows all messages in order so you can follow the dispatch chain.

Solid understanding of template matching pays off every time you work on a complex stylesheet. Once you know how priorities and built-ins interact, most “unexpected output” bugs become obvious.