CSS counters() Function

The counters() function enables you to display nested counters that have been generated by an element and its parent/s.

Every element has a collection of zero or more counters, which are inherited through the document tree in a way similar to inherited property values. You can create and manipulate counters with the counter-increment, counter-reset, and (CSS3 introduced) counter-set properties. Counters have no visible effect by themselves, but they can be used with the counters() and counter() functions, which allow the values of the counters to be displayed, in the format you specify.

A counter's value can be displayed with the content property.

While the counter() (singular) function can be used to output a counter, the counters() (plural) function can be used to output nested counters.

For example, you can use the counters() function to output counters for nested lists. Like this:

View Output

You can display an element's counter in upper-roman, decimal, georgian, etc. You can also provide Unicode code points to specify special symbols or icons to be used as the marker representation.

Official Syntax

The counters() function has two forms: counters(name, string) or counters(name, string, style). The generated text is the value of all counters with the given name in scope at this pseudo-element, from outermost to innermost separated by the specified string. The counters are rendered in the indicated style (decimal by default).

The official syntax of the counters() function is as follows:

Below is an explanation of each of these values.

Possible Values

ident

This is an identifier that specifies the name of the counter. This is the name that is used by the counter-reset, counter-increment, and/or counter-set properties to create and manipulate the counter.

string

This is a string that is used as a separator between the numbers of the nested levels. For example a dot (.) would be used to generate a counter that looks like this: 11.2.0.

counter-style

The counter-style provides the counter style to be applied to the counter's representation.

A counter style can be defined using the @counter-style at-rule, the symbols() function, or one of the CSS predefined counter styles.

Here's a brief overview of each one.

The @counter-style At-Rule

The @counter-style at-rule allows you to define your own counter style for use within your lists and/or generated content. It accepts a name, followed by a number of descriptors, which define the counter style.

The symbols() Function

The symbols() function is a stripped down alternative to the @counter-style at-rule. It provides a quick and easy way to create a counter style directly inline within the property without adding the extra code that an at-rule requires.

The Predefined Counter Styles

CSS includes a number of predefined counter styles. These are keywords that represent some of the more common counter styles.

Here's an example of using lower-roman:

Here's a working example:

View Output

The predefined counter styles come under four categories; Numeric, Alphabetic, Symbolic, and Longhand East Asian Counter Styles.

Numeric
decimal
Western decimal numbers (e.g., 1, 2, 3, ...).
decimal-leading-zero
Decimal numbers padded by initial zeros (e.g., 01, 02, 03, ...)
cjk-decimal
Han decimal numbers (e.g., 一, 二, 三, ...)
lower-roman
Lowercase ASCII Roman numerals (e.g., i, ii, iii, ...)
upper-roman
Uppercase ASCII Roman numerals (e.g., I, II, III, ...)
armenian
Traditional uppercase Armenian numbering (e.g., Ա, Բ, Գ, ...)
georgian
Traditional Georgian numbering (e.g., ა, ბ, გ, ...)
hebrew
Traditional Hebrew numbering (e.g., ג, ב, א, ...)
Alphabetic
lower-alpha
lower-latin
Lowercase ASCII letters (e.g., a, b, c, ...).
upper-alpha
upper-latin
Uppercase ASCII letters (e.g., A, B, C, ...).
lower-greek
Lowercase classical Greek (e.g., α, β, γ, ...)
hiragana
Dictionary-order hiragana lettering (e.g., あ, い, う, ...)
hiragana-iroha
Iroha-order hiragana lettering (e.g., い, ろ, は, ...)
katakana
Dictionary-order katakana lettering (e.g., ア, イ, ウ, ...)
katakana-iroha
Iroha-order katakana lettering (e.g., イ, ロ, ハ, ...)
Symbolic
disc
A filled circle, similar to U+2022 (•)
circle
A hollow circle, similar to U+25E6 (◦)
square
A filled square, similar to U+25FE (◾)
disclosure-open
disclosure-closed

Symbols appropriate for indicating an open or closed disclosure widget, such as when using the HTML details element.

For example, disclosure-open might use the U+25B8 character (▸) and disclosure-closed might use the U+25BE character (▾).

Longhand East Asian Counter Styles
japanese-informal
Informal Japanese Kanji numbering.
japanese-formal
Formal Japanese Kanji numbering.
korean-hangul-formal
Korean Hangul numbering.
korean-hanja-informal
Informal Korean Hanja numbering.
korean-hanja-formal
Forman Korean Han (Hanja) numbering.
simp-chinese-informal
Simplified Chinese informal numbering.
simp-chinese-formal
Simplified Chinese formal numbering.
trad-chinese-informal
Traditional Chinese informal numbering.
trad-chinese-formal
Traditional Chinese informal numbering.
cjk-ideographic
This is a legacy style that is the same as trad-chinese-informal

none

Represents the empty string (""). No counter is displayed.

CSS Specifications