CSS Reference ยท Functions
The counter() and counters() functions
Reference for the CSS counter() and counters() functions: display counter values in generated content, nested numbering like 1.2.3, styles and examples.
counter() and counters() output the current value of a CSS counter as text. They only work in generated content, which means the content property of ::before, ::after and ::marker. The counter itself is created and changed with counter-reset, counter-increment and counter-set.
Use counter() to print one number, such as "Step 3". Use counters() for nested numbering such as "2.1.4", where it joins the values of every nested counter with a separator you choose.
li::before { content: counter(item) ". "; } li li::before { content: counters(item, ".") " "; }
Try it
Each nested <ol> runs counter-reset: item again, which creates a new counter with the same name inside the outer one. counters(item, ".") then lists the values of all those nested counters, outermost first.
Syntax
counter( <counter-name> , <counter-style>? ) counters( <counter-name> , <string> , <counter-style>? )
- Initial value: not applicable (functions).
- Where it works: values of
content(and other places that accept a<content-list>). - Counter style default:
decimal. - Computed value: the function with its resolved arguments; the used value is a string.
Values
| Syntax and arguments | Description |
|---|---|
<counter-name> |
The identifier of the counter, as used in counter-reset and counter-increment. Case-sensitive. |
<string> (counters() only) |
The separator inserted between values, for example "." or " / ". |
<counter-style> |
Optional. A named style such as decimal, decimal-leading-zero, lower-alpha, upper-alpha, lower-roman, upper-roman, lower-greek, or a style defined with @counter-style. |
Usage notes
- Counters need a reset. If you increment a counter that was never reset, the browser creates one for you, but explicit resets make the scope clear and avoid surprises.
- Scope follows the tree. A counter reset on an element is visible to that element, its following siblings and their descendants. That is why numbering restarts in each section when you reset on the section element.
counter()shows only the innermost counter. In nested lists it shows just the number at the current level; switch tocounters()if you want the whole path.- Hidden elements do not count. An element with
display: nonedoes not increment counters, butvisibility: hiddenelements do. - Counters are decoration. Generated content is not reliably exposed to every assistive technology and cannot be selected or copied consistently. Do not put essential information only in a counter; native
<ol>numbering is better when the numbers carry meaning. - Lists have a built-in counter.
list-itemis an implicit counter, socounter(list-item)works in list markers. - Prefer
::markerfor list numbers.li::marker { content: counter(list-item) ") "; }changes the marker without losing list semantics.
Browser support
Supported in every browser for a long time; counter-set and counters() with custom counter styles are also widely available.
Related
counter-resetโ creates a countercounter-incrementโ increases a countercounter-setโ sets a counter to a valuecontentโ where the functions are used- Lesson: CSS Counters