CSS counter() Function

The counter() function enables you to display the counter that has been generated by an element.

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 counter() and counters() functions, which allow the values of the counters to be displayed, in the format you specify.

For example, you can use the counter() function to output 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.

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

As well as numbered headings, you could also use the counter() function to do things like display numbered figure elements, img elements, table of contents, etc.

Official Syntax

The counter() function has two forms: counter(name) or counter(name, style). The generated text is the value of the innermost counter of the given name in scope at this pseudo-element; it is formatted in the indicated style (decimal by default).

The official syntax of the counter() 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.

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.

Here's an example that uses Unicode code points for the marker representations:

These Unicode code points represent circled numbers. So the result could look something like this:

Example of headings with circled numbers.
Headings with circled numbers.

Here's a working example. If your browser supports the @counter-style rule, it should look like the above image:

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.

Here's an example that uses the same Unicode code points as the previous example:

These Unicode code points represent circled numbers. So as with the previous example, the result could look something like this:

Example of headings with circled numbers.
Headings with circled numbers.

Here's a working example. If your browser supports the symbols() function, this should look like the above image:

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:

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