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:

<!doctype html>
<title>Example</title>
<style>
  ul {
    list-style: none;
    counter-reset: nestedCounter;
  }  
  ul li {
    counter-increment: nestedCounter;
    line-height: 1.4;
  }  
  ul li:before {
    content: counters(nestedCounter, ".") " - ";
    font-weight: bold;
  }
</style>

<ul>
  <li>Fruit
    <ul>
      <li>Apples
        <ul>
          <li>Green ones</li>
          <li>Red ones</li>
        </ul>
      </li>
      <li>Oranges
        <ul>
          <li>Small ones</li>
          <li>Big ones</li>
        </ul>
      </li>
    </ul>  
  </li>
  <li>Vegetables
    <ul>
      <li>Carrots
        <ul>
          <li>Orange ones</li>
          <li>Purple ones</li>
        </ul>
      </li>
      <li>Potatoes
        <ul>
          <li>Fresh ones</li>
          <li>Rotten ones</li>
        </ul>
      </li>
    </ul>  
  </li>
  <li>Fish
    <ul>
      <li>Big Ones
        <ul>
          <li>Mekong Catfish</li>
        </ul>
      </li>
      <li>Small Ones
        <ul>
          <li>Piranha</li>
          <li>Gold Fish</li>
          <li>Black Molly</li>
        </ul>
      </li>
    </ul>  
  </li>
</ul>

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:

<!doctype html>
<title>Example</title>
<style>
  ul {
    list-style: none;
    counter-reset: nestedCounter;
  }  
  ul li {
    counter-increment: nestedCounter;
    line-height: 1.4;
  }  
  ul li:before {
    content: counters(nestedCounter, ".", lower-roman) " - ";
    font-weight: bold;
  }
</style>

<ul>
  <li>Fruit
    <ul>
      <li>Apples
        <ul>
          <li>Green ones</li>
          <li>Red ones</li>
        </ul>
      </li>
      <li>Oranges
        <ul>
          <li>Small ones</li>
          <li>Big ones</li>
        </ul>
      </li>
    </ul>  
  </li>
  <li>Vegetables
    <ul>
      <li>Carrots
        <ul>
          <li>Orange ones</li>
          <li>Purple ones</li>
        </ul>
      </li>
      <li>Potatoes
        <ul>
          <li>Fresh ones</li>
          <li>Rotten ones</li>
        </ul>
      </li>
    </ul>  
  </li>
  <li>Fish
    <ul>
      <li>Big Ones
        <ul>
          <li>Mekong Catfish</li>
        </ul>
      </li>
      <li>Small Ones
        <ul>
          <li>Piranha</li>
          <li>Gold Fish</li>
          <li>Black Molly</li>
        </ul>
      </li>
    </ul>  
  </li>
</ul>

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, ...).

The decimal counter style cannot be overridden by the @counter-style at-rule, so it is always available as an ultimate fallback style.
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

The counters() function is defined in CSS Lists and Counters Module Level 3 (W3C Working Draft)
It's also defined in CSS2 (W3C Recommendation 07 June 2011)

CSS counters() Function

Official Syntax

Possible Values

`ident`

`string`

`counter-style`

The `@counter-style` At-Rule

The `symbols()` Function

The Predefined Counter Styles

Numeric

Alphabetic

Symbolic

Longhand East Asian Counter Styles

`none`

CSS Specifications

CSS counters() Function

Official Syntax

Possible Values

ident

string

counter-style

The @counter-style At-Rule

The symbols() Function

The Predefined Counter Styles

Numeric

Alphabetic

Symbolic

Longhand East Asian Counter Styles

none

CSS Specifications

`ident`

`string`

`counter-style`

The `@counter-style` At-Rule

The `symbols()` Function

`none`