counters()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨July 2015⁩.

The counters() function enables combining markers when nesting counters. The function returns a string that concatenates the current values of the named and nested counters, if any are present, with the string provided. The third, optional parameter enables defining the list style.

The counters() function is generally used within <string> value is supported.

The counters() function has two forms: counters(<name>, <string>) and counters(<name>, <string>, <style>). The generated text is the value of all counters with the given <name>, arranged from the outermost to the innermost, and separated by the specified <string>. The counters are rendered in the <style> indicated, defaulting to decimal if no <style> is specified.

Try it

ol {
  counter-reset: index;
  list-style-type: none;
}

li::before {
  counter-increment: index;
  content: counters(index, ".", decimal) " ";
}

<ol>
  <li>Mars</li>
  <li>
    Saturn
    <ol>
      <li>Mimas</li>
      <li>Enceladus</li>
      <li>
        <ol>
          <li>Voyager</li>
          <li>Cassini</li>
        </ol>
      </li>
      <li>Tethys</li>
    </ol>
  </li>
  <li>
    Uranus
    <ol>
      <li>Titania</li>
    </ol>
  </li>
</ol>

Syntax

css

/* Basic usage  - style defaults to decimal */
counters(counter-name, '.');

/* changing the counter display */
counters(counter-name, '-', upper-roman)

A counter() function) is what makes it useful by returning developer-defined content.

Values

The counters() function accepts two or three parameters. The first parameter is the <counter-name>. The second parameter is the concatenator <string>. The optional third parameter is the <counter-style>.

<counter-name>: A symbols() function can be used instead of a named counter in browsers that support symbols().
<string>: Any number of text characters. Non-Latin characters must be encoded using their Unicode escape sequences: for example, \000A9 represents the copyright symbol.
<counter-style>: A counter style name or a predefined counter style. If omitted, the counter-style defaults to decimal.

The return value is a string containing all the values of all the counters in the element's CSS counters set named <counter-name> in the counter style defined by <counter-style> (or decimal, if omitted). The return string is sorted in outermost-first to innermost-last order, joined by the <string> specified.

Note: For information about non-concatenated counters, see the counter() function, which omits the <string> as a parameter.

Formal syntax

<counters()> = 
  counters( <counter-style-name>  <string> |
  numeric     <url>           |
  <element()>     [ <image-src>]! )  

<image-set()> = 
  image-set( <image-set-option><url>     | <resolution> ?  

<cf-image> = 
  ]  <hash-token>

Examples

Comparing default counter value to uppercase roman numerals

This example includes two counters() functions: one with <counter-style> set and the other defaulting to decimal.

HTML

html

<ol>
  <li>
    <ol>
      <li></li>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <li></li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

CSS

css

ol {
  counter-reset: listCounter;
}
li {
  counter-increment: listCounter;
}
li::marker {
  content:
    counters(listCounter, ".", upper-roman) ") ";
}
li::before {
  content:
    counters(listCounter, ".") " == "
    counters(listCounter, ".", lower-roman);
}

Result

Comparing decimal-leading-zero counter value to lowercase letters

This example includes three counters() functions, each with different <string> and <counter-style> values.

HTML

html

<ol>
  <li>
    <ol>
      <li></li>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <li></li>
        </ol>
      </li>
    </ol>
  </li>
</ol>

CSS

css

ol {
  counter-reset: count;
}
li {
  counter-increment: count;
}
li::marker {
  content:
    counters(count, "-", decimal-leading-zero) ") ";
}
li::before {
  content:
    counters(count, "~", upper-alpha) " == "
    counters(count,  "*", lower-alpha);
}

Result

Specifications

Specification
CSS Lists and Counters Module Level 3 # counter-functions
CSS Counter Styles Level 3 # extending-css2

Browser compatibility

Help improve MDN

Learn how to contribute

This page was last modified on ⁨Nov 7, 2025⁩ by MDN contributors.

View this page on GitHub • Report a problem with this content