counters()
==========

The **`counters()`** CSS 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 pseudo-element through the `content` property, but theoretically, it can be used wherever a `<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
------

Syntax
------


```css
/\* Simple usage - style defaults to decimal \*/
counters(countername, '.');

/\* changing the counter display \*/
counters(countername, '-', upper-roman)
```


A counter has no visible effect by itself. The `counters()` function (and `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 `<custom-ident>` identifying the counters, which is the same case-sensitive name used for the `counter-reset` and `counter-increment` properties. The name cannot start with two dashes and can't be `none`, `unset`, `initial`, or `inherit`. Alternatively, for inline, single-use counters, the `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 `symbols()` function. The counter style name can be a simple predefined style such as numeric, alphabetic, or symbolic, a complex longhand predefined style such as East Asian or Ethiopic, or another 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-name> , <string> , <counter-style>? )    
  
<counter-style> =   
  <counter-style-name>  |  
  <symbols()>             
  
<symbols()> =   
  symbols( <symbols-type>? [ <string> | <image> ]+ )    
  
<symbols-type> =   
  cyclic      |  
  numeric     |  
  alphabetic  |  
  symbolic    |  
  fixed         
  
<image> =   
  <url>       |  
  <gradient>    
  
<url> =   
  <url()>  |  
  <src()>    
  
<url()> =   
  url( <string> <url-modifier>\* )  |  
  <url-token>                        
  
<src()> =   
  src( <string> <url-modifier>\* )    
  
```

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>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <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>
      <li></li>
    </ol>
  </li>
  <li></li>
  <li></li>
  <li>
    <ol>
      <li></li>
      <li>
        <ol>
          <li></li>
          <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 |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using CSS Counters
* `counter-set` property
* `counter-reset` property
* `counter-increment` property
* `@counter-style` at-rule
* CSS `counter()` function
* `::marker` pseudo-element
* CSS lists and counters module
* CSS counter styles module
* CSS generated content module