The xsl:number element outputs the sequential number of a node in the source document.

If the select attribute is present, this is an expression that selects the node to be numbered. The default is ., the context node.

The instruction takes an attribute count whose value is a pattern indicating which nodes to count; the default is to match all nodes of the same type and name as the current node.

The level attribute may take three values: "single", "any", or "multiple". The default is "single". This defines the rules for calculating a number.

There is also an optional from attribute, which is also a pattern. The exact meaning of this depends on the level.

The calculation is as follows:


If the current node matches the pattern, the counted node is the current node. Otherwise the counted node is the innermost ancestor of the current node that matches the pattern. If no ancestor matches the pattern, the result is zero. If the from attribute is present, the counted node must be a descendant of a node that matches the "from" pattern.The result is one plus the number of elder siblings of the counted node that match the count pattern.


The result is the number of nodes in the document that match the count pattern, that are at or before the current node in document order, and that follow in document order the most recent node that matches the "from" pattern, if any. Typically this is used to number, say, the diagrams or equations in a document, or in some section or chapter of a document, regardless of where the diagrams or equations appear in the hierarchic structure.


The result of this is not a single number, but a list of numbers. There is one number in the list for each ancestor of the current element that matches the count pattern and that is a descendant of the anchor element. Each number is one plus the number of elder siblings of the relevant element that match the count pattern. The order of the numbers is "outwards-in".

There is an optional format attribute which controls the output format. This contains an alternating sequence of format-tokens and punctuation-tokens. A format-token is any sequence of alphanumeric characters, a punctuation-token is any other sequence. The following values (among others) are supported for the format-token:


Sequence 1, 2, 3, ... 10, 11, 12, ...


Sequence 001, 002, 003, ... 010, 011, 012, ... (any number of leading zeroes)


Sequence a, b, c, ... aa, ab, ac, ...


Sequence A, B, C, ... AA, AB, AC, ...


Sequence i, ii, iii, iv, ... x, xi, xii, ...


Sequence I, II, III, IV, ... X, XI, XII, ...

There is also support for various Japanese sequences (Hiragana, Katakana, and Kanji) using the format tokens &#x3042, &#x30a2, &#x3044, &#x30a4, &#x4e00, and for Greek and Hebrew sequences.

The format token "w" gives the sequence "one", "two", "three", ... , while "W" gives the same in upper-case, and "Ww" in title case. The language is determined by the lang attribute, for example lang="en" for English. Saxon currently supports Belgian French (fr-BE), Danish (da), Dutch (nl), English (en), Flemish (nl-BE), French (fr), German (de), Italian (it), Swedish (sw). Additional languages can be achieved by writing a Numberer class, as described in Localizing numbers and dates.

The default format is "1".

A sequence of Unicode digits other than ASCII digits (for exaple, Tibetan digits) can be used, and will result in decimal numbering using those digits.

Similarly, any other character classified as a letter can be used, and will result in "numbering" using all consecutive Unicode letters following the one provided. For example, specifying "x" will give the sequence x, y, z, xx, xy, xz, yx, yy, yz, etc. Specifying the Greek letter alpha (²) will cause "numbering" using the Greek letters up to "Greek letter omega with tonos" (Î). Only "i" and "I" (for roman numbering), and the Japanese characters listed above, are exceptions to this rule.

Successive format-tokens in the format are used to process successive numbers in the list. If there are more format-tokens in the format than numbers in the list, the excess format-tokens and punctuation-tokens are ignored. If there are fewer format-tokens in the format than numbers in the list, the last format-token and the punctuation-token that precedes it are used to format all excess numbers, with the final punctuation-token being used only at the end.

























This character may be preceded or followed by arbitrary punctuation (anything other than these characters or XML special characters such as "<") which is copied to the output verbatim. For example, the value 3 with format "(a)" produces output "(c)".

It is also possible to use xsl:number to format a number obtained from an expression. This is achieved using the value attribute of the xsl:number element. If this attribute is present, the count, level, and from attributes are ignored.

With large numbers, the digits may be split into groups. For example, specify grouping-size="3" and grouping-separator="/" to have the number 3000000 displayed as "3/000/000".

Negative numbers are always output in conventional decimal notation, regardless of the format specified.

Example: This example outputs the title child of an H2 element preceded by a composite number formed from the sequential number of the containing H1 element and the number of the containing H2 element.

<xsl:template match="H2/TITLE"> <xsl:number count="H1">.<xsl:number count="H2"> <xsl:text> </xsl:text> <xsl:apply-templates/> </xsl:template>

XSLT 3.0 (and Saxon 9.5) introduces a new attribute start-at which allows numbering to start at a number other than one.

In XSLT 3.0 some of the capabilities of the xsl:number instruction - specifically the formatting capabilities - are more conveniently packaged via the new format-integer() function, which is also available in XPath and XQuery.