XSLT - XSLT <xsl:next-match> for Template Chaining

<xsl:next-match> is an advanced XSLT instruction used to invoke the next template rule that would have matched the current node, rather than starting template processing from the beginning. It is especially useful when several templates can match the same node and one template needs to extend or customize the behavior of another.

The feature is available in XSLT 2.0 and later. The W3C XSLT 3.0 specification categorizes xsl:next-match among the instructions used to invoke templates. (W3C)

1. Why <xsl:next-match> is needed

Normally, when XSLT processes a node, it selects the template with the highest applicable priority. For example:

<products>
    <product>
        <name>Laptop</name>
        <price>75000</price>
    </product>
</products>

Suppose you have a general template for product:

<xsl:template match="product">
    <div>
        <xsl:value-of select="name"/>
    </div>
</xsl:template>

Now imagine that you want to create another template for product that performs some additional processing:

<xsl:template match="product" priority="2">
    ...
</xsl:template>

The higher-priority template takes control, and the original template is no longer automatically executed.

This can create a problem when you want to modify or extend existing processing rather than completely replace it.

This is where <xsl:next-match> becomes useful.

2. Basic syntax

The basic syntax is:

<xsl:next-match/>

It is normally placed inside a template:

<xsl:template match="product">
    <xsl:next-match/>
</xsl:template>

When the processor reaches <xsl:next-match>, it looks for the next applicable template rule for the current node.

This is different from:

<xsl:apply-templates/>

because xsl:apply-templates starts a new template selection process for selected nodes, whereas xsl:next-match continues the template-selection chain for the current node.

3. Understanding template priority

To understand xsl:next-match, you should first understand template priority.

Consider:

<xsl:template match="product">
    <general>
        <xsl:value-of select="name"/>
    </general>
</xsl:template>

<xsl:template match="product" priority="2">
    <special>
        <xsl:value-of select="name"/>
    </special>
</xsl:template>

Both templates match product.

The second template has:

priority="2"

Therefore, it has higher priority and is selected first.

Without xsl:next-match, processing stops with the selected template.

With xsl:next-match, the selected template can explicitly invoke the next applicable template.

4. Simple example

Consider this XML:

<catalog>
    <product>
        <name>Laptop</name>
        <price>75000</price>
    </product>
</catalog>

The stylesheet can contain:

<xsl:stylesheet version="3.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <xsl:output method="xml" indent="yes"/>

    <xsl:template match="product">
        <product-details>
            <xsl:value-of select="name"/>
        </product-details>
    </xsl:template>

    <xsl:template match="product" priority="2">
        <xsl:message>Processing product</xsl:message>

        <xsl:next-match/>
    </xsl:template>

</xsl:stylesheet>

For the product element, the processor first selects:

<xsl:template match="product" priority="2">

Inside that template, it encounters:

<xsl:next-match/>

The processor then looks for the next applicable template and finds:

<xsl:template match="product">

The second template therefore gets an opportunity to extend the behavior of the first.

5. <xsl:next-match> versus <xsl:apply-templates>

These two instructions may appear similar, but their purposes are different.

xsl:apply-templates

<xsl:apply-templates select="product"/>

This tells XSLT to process selected nodes using the normal template-selection mechanism.

It is generally used when you want to move processing to other nodes.

xsl:next-match

<xsl:next-match/>

This tells XSLT to invoke the next matching template for the same current node.

Therefore:

apply-templates
    |
    +-- selects nodes
    +-- starts template matching for those nodes

next-match
    |
    +-- keeps the current node
    +-- moves to the next applicable template

This distinction is one of the most important concepts when learning xsl:next-match.

6. Extending an existing template

One of the most useful applications of xsl:next-match is extending an existing template.

Suppose a general stylesheet already processes employees:

<xsl:template match="employee">
    <employee>
        <name>
            <xsl:value-of select="name"/>
        </name>
        <department>
            <xsl:value-of select="department"/>
        </department>
    </employee>
</xsl:template>

Later, you want special processing for managers.

You could create:

<xsl:template match="employee[@role='manager']">
    <xsl:next-match/>
</xsl:template>

The specialized template can perform additional work before or after the next template.

For example:

<xsl:template match="employee[@role='manager']">
    <xsl:message>
        Manager employee detected
    </xsl:message>

    <xsl:next-match/>
</xsl:template>

This allows you to add behavior without copying the entire original template.

7. Why this reduces duplicate code

Without xsl:next-match, developers may copy an entire template just to make a small modification.

For example:

<xsl:template match="employee">
    <employee>
        <name>
            <xsl:value-of select="name"/>
        </name>
        <department>
            <xsl:value-of select="department"/>
        </department>
        <location>
            <xsl:value-of select="location"/>
        </location>
    </employee>
</xsl:template>

If a special employee type needs additional processing, copying all this code creates duplication.

If the original template later changes, you may have to update multiple copies.

With xsl:next-match, the specialized template can delegate the normal processing to the next template.

This supports a more maintainable stylesheet design.

8. Processing before and after <xsl:next-match>

An important characteristic is that the instruction can be surrounded by other instructions.

For example:

<xsl:template match="employee[@role='manager']">

    <before>
        <xsl:text>Manager processing started</xsl:text>
    </before>

    <xsl:next-match/>

    <after>
        <xsl:text>Manager processing completed</xsl:text>
    </after>

</xsl:template>

Conceptually, processing occurs as:

Specialized template
        |
        v
Before processing
        |
        v
xsl:next-match
        |
        v
Next matching template
        |
        v
Return to specialized template
        |
        v
After processing

This makes xsl:next-match useful for implementing layered transformations.

9. Multiple template layers

The concept becomes particularly powerful when several templates match the same node.

For example:

<xsl:template match="product">
    <xsl:text>Base processing</xsl:text>
</xsl:template>

<xsl:template match="product" priority="2">
    <xsl:text>Second layer</xsl:text>
    <xsl:next-match/>
</xsl:template>

<xsl:template match="product" priority="3">
    <xsl:text>Third layer</xsl:text>
    <xsl:next-match/>
</xsl:template>

The highest-priority template is selected first.

The processing can then move through the matching templates:

Priority 3 template
       |
       | xsl:next-match
       v
Priority 2 template
       |
       | xsl:next-match
       v
Priority 1 template

This creates a template chain.

Each template can add, modify, or monitor some aspect of the transformation.

10. Template chaining with modes

xsl:next-match can also be used in combination with modes.

For example:

<xsl:mode name="display"/>

<xsl:template match="product" mode="display">
    <div>
        <xsl:value-of select="name"/>
    </div>
</xsl:template>

<xsl:template match="product[@featured]" mode="display" priority="2">
    <strong>Featured Product</strong>

    <xsl:next-match/>
</xsl:template>

The mode determines which group of template rules participates in processing.

The specialized template can then call the next applicable template within that template-processing context.

11. Relationship with <xsl:apply-imports>

xsl:next-match is also important to distinguish from:

<xsl:apply-imports/>

Both can be used to delegate processing to another template, but they do not mean the same thing.

xsl:apply-imports specifically invokes an applicable template from an imported stylesheet, subject to the rules governing stylesheet import precedence.

xsl:next-match, on the other hand, moves to the next matching template rule based on the template rules applicable to the current node.

The W3C specification treats xsl:next-match, xsl:apply-templates, and xsl:apply-imports as distinct mechanisms for invoking templates. (W3C)

12. Practical example

Consider this XML:

<employees>
    <employee role="manager">
        <name>John</name>
        <department>Sales</department>
    </employee>

    <employee role="developer">
        <name>Sarah</name>
        <department>Technology</department>
    </employee>
</employees>

A basic template can process all employees:

<xsl:template match="employee">
    <employee>
        <name>
            <xsl:value-of select="name"/>
        </name>
        <department>
            <xsl:value-of select="department"/>
        </department>
    </employee>
</xsl:template>

Now a special rule can identify managers:

<xsl:template match="employee[@role='manager']" priority="2">

    <manager>
        <xsl:value-of select="name"/>
    </manager>

    <xsl:next-match/>

</xsl:template>

The manager-specific template is selected first because it is more specific and has a higher priority.

The xsl:next-match instruction then allows the general employee template to process the same node.

This is useful when a specialized rule should add behavior without completely abandoning the general rule.

13. Important point about output

When learning xsl:next-match, it is important to remember that the output generated by both templates is normally part of the same transformation result.

For example:

<xsl:template match="product">
    <general>
        <xsl:value-of select="name"/>
    </general>
</xsl:template>

<xsl:template match="product" priority="2">
    <special>
        <xsl:value-of select="name"/>
    </special>

    <xsl:next-match/>
</xsl:template>

The specialized template generates:

<special>...</special>

Then the next template generates:

<general>...</general>

Therefore, developers need to design the output structure carefully. Calling xsl:next-match does not automatically replace the output generated by the current template.

14. Advantages of <xsl:next-match>

Code reuse

It allows specialized templates to reuse existing processing rather than duplicating the complete template.

Better maintainability

Changes to a general template can automatically benefit specialized processing that delegates to it.

Layered processing

Multiple template rules can contribute different processing stages.

Extensibility

A base stylesheet can provide general processing while another stylesheet or customization layer can add specialized behavior.

Separation of responsibilities

Different templates can handle different aspects of the transformation without placing all logic into one large template.

15. Common mistakes

Mistake 1: Assuming it calls the same template again

It does not recursively call the current template.

<xsl:next-match/>

means to continue with the next applicable template rule.

Mistake 2: Confusing it with apply-templates

xsl:apply-templates normally starts template processing for selected nodes.

xsl:next-match continues the matching chain for the current node.

Mistake 3: Forgetting template priority

If you do not understand which template has higher priority, it can be difficult to predict which template will execute first.

Mistake 4: Creating unwanted output

If both templates generate elements, calling xsl:next-match can cause output from both templates to appear.

Mistake 5: Using it unnecessarily

If a single template can cleanly perform the required operation, introducing multiple template layers may make the stylesheet harder to understand.

16. When should you use <xsl:next-match>?

Use it when:

  • A general template already performs useful processing.

  • A more specific template needs to add functionality.

  • You want to avoid duplicating a large template.

  • Several template rules should contribute to the processing of the same node.

  • You are designing an extensible or layered stylesheet.

  • You need behavior before and after the normal processing of a node.

Avoid it when there is no meaningful template chain. In simple transformations, ordinary xsl:apply-templates or a single template is usually easier to understand.

17. Summary

<xsl:next-match> is an XSLT 2.0/3.0 instruction that allows a template to invoke the next applicable template rule for the current node. It is particularly useful for extending existing template behavior without copying the entire template.

The basic pattern is:

<xsl:template match="some-node" priority="2">

    <!-- Additional processing -->

    <xsl:next-match/>

    <!-- More processing -->

</xsl:template>

The key idea is:

Current template
      |
      v
Additional processing
      |
      v
xsl:next-match
      |
      v
Next applicable template
      |
      v
Continue transformation

In practical XSLT development, this makes template rules work more like layers. A general rule can provide the standard behavior, while more specialized rules can add functionality before or after that behavior. The W3C specification explicitly defines xsl:next-match as an instruction for invoking templates and also defines how it participates in streamability analysis in XSLT 3.0. (W3C)