Skip to content
Tutorials Center
My learning

Topics

Lesson 87 of 139 ยท Lists, Tables and Forms

CSS Counters

Number headings, figures and nested lists with CSS counters. Learn counter-reset, counter-increment, counter(), counters() and styled nested numbering like 1.2.3.

Ordered lists number themselves, but what about everything else? Book chapters, figure captions, legal clauses, steps in a tutorial and footnotes all need numbers too, and typing them by hand breaks the moment you insert a new item in the middle. CSS counters are variables that the browser counts up as it walks through the document, and you can print their values anywhere with generated content.

In this lesson you will create counters, increment them, display them with counter() and counters(), and build nested outline numbering such as 2.1.3.

The three parts of a counter

Working with a counter always involves three steps:

  1. Create (reset) it on a container with counter-reset.
  2. Increment it on each element you want to count with counter-increment.
  3. Display it with the counter() function inside a content declaration, usually on ::before.
CSS
article { counter-reset: section; }          /* 1. start at 0 */

h2 { counter-increment: section; }           /* 2. +1 for every h2 */

h2::before {
  content: "Section " counter(section) ": "; /* 3. print it */
}

Counter names are your own identifiers, like section, figure or step. They are not strings, so don't quote them. The browser processes the document in order, so the first <h2> shows 1, the second shows 2, and so on.

Numbering headings

Add a new <h2> between two others. Every chapter after it renumbers itself, with no edits to the text.

Starting values and step sizes

Both counter-reset and counter-increment accept an optional number after the name:

CSS
ol.countdown { counter-reset: n 11; }     /* start at 11 */
ol.countdown li { counter-increment: n -1; } /* count down: 10, 9, 8... */

.evens { counter-reset: e; }
.evens li { counter-increment: e 2; }     /* 2, 4, 6... */

Remember that counter-reset: n 11 sets the value before the first increment. With an increment of -1, the first item displays 10.

You can also manage several counters on one element by listing them with spaces:

CSS
body { counter-reset: figure table; }

Declarations replace, they don't add up. counter-reset and counter-increment are ordinary properties, so the cascade picks one winning value. If one rule says counter-reset: figure and a later rule on the same element says counter-reset: table, only table is reset. List every counter in one declaration.

There is also a counter-set property. It sets an existing counter to a value without creating a new one, which is handy when you need to jump, for example, from appendix numbering back to a specific page number.

Formatting the number

counter() takes an optional second argument: any list style type. That means your counters can use letters, Roman numerals or other writing systems:

CSS
h2::before { content: counter(chapter, upper-roman) ". "; }   /* I. II. III. */
.note::before { content: "Note " counter(note, lower-alpha); } /* Note a, Note b */

Generated text from ::before is presented by most screen readers, but it is not part of the DOM text and cannot be selected or copied in most browsers. Use counters for numbering that helps the reader follow along, and keep any number that people must quote, such as a clause in a contract, in the HTML.

Nested numbering with counters()

Here's where counters get powerful. Every time counter-reset runs on a nested element, it creates a new instance of the counter scoped to that element. So in a nested list, each <ol> has its own instance, and the outer ones are still alive.

The counters() function (plural) prints all instances of the counter from the outermost to the innermost, joined by a string you choose:

CSS
ol { counter-reset: item; list-style: none; }
li { counter-increment: item; }
li::before { content: counters(item, ".") " "; }

That one rule produces 1, 1.1, 1.2, 1.2.1, 2 and so on, to any depth.

Outline numbering with counters()

Try nesting a fourth level. You don't need any more CSS, because each new <ol> creates another counter instance automatically.

The native list markers could do this too, in modern browsers, because ordered lists use a built-in counter called list-item. You can even write li::marker { content: counters(list-item, ".") " "; }. The ::before approach shown above gives you more control over spacing and style, which is why you will see it more often.

Counting things that aren't lists

Counters work on any element. A common case is numbering figures and referring to them in captions. Another is a step-by-step guide with big circular step badges, where the badge style would be impossible with list markers.

Step badges and figure numbers

Both counters are reset once, on <body>, in a single declaration. The steps and figures are interleaved, yet each keeps its own count.

Where counters reset (scope rules)

The rules that decide which instance an element sees are worth knowing when something numbers strangely:

  • A counter-reset creates a new instance on the element. Its descendants and its following siblings (and their descendants) see that instance.
  • If an element increments or displays a counter that was never reset, the browser quietly creates one on that element, starting from 0. This is a common source of every item showing "1": the reset is missing, or it's on the wrong element.
  • Elements with display: none don't increment counters. Elements hidden with visibility: hidden still do.

When numbers look wrong, check two things: is the reset on a common ancestor of everything being counted, and is it in just one declaration?

Custom counter styles with @counter-style

The built-in styles cover decimal digits, letters, Roman numerals and dozens of writing systems. When you need something else, such as circled digits, zero-padded numbers or your own bullet characters, define a style with the @counter-style at-rule. You give it a name, then use that name anywhere a list style is accepted: in list-style-type, or as the second argument of counter() and counters().

CSS
@counter-style circled {
  system: fixed;
  symbols: "โ‘ " "โ‘ก" "โ‘ข" "โ‘ฃ" "โ‘ค" "โ‘ฅ" "โ‘ฆ" "โ‘ง" "โ‘จ" "โ‘ฉ";
  suffix: " ";
}

ol.steps { list-style-type: circled; }
h2::before { content: counter(chapter, circled); }

The system descriptor decides how the browser turns a number into symbols:

system How it counts Good for
cyclic Loops through the symbols forever Bullets that alternate
fixed Uses each symbol once, then falls back A short, known number of items
numeric Treats the symbols as digits of a positional system Binary, hexadecimal, other digit sets
alphabetic Like a, b โ€ฆ z, aa, ab Letter sequences with any alphabet
symbolic Repeats the symbol: *, **, *** Footnote marks
additive Adds up weighted symbols, like Roman numerals Tally marks and similar systems
extends <name> Copies an existing style and changes a few descriptors Small tweaks such as padding or a new suffix

A few more descriptors fine-tune the result:

  • prefix and suffix add text before and after the marker. The default suffix is ". ", which is why list numbers end in a period.
  • pad sets a minimum length: pad: 2 "0" turns 7 into 07.
  • range limits which numbers the style handles, and fallback names the style used outside that range (or after a fixed style runs out). The default fallback is decimal.
  • negative sets the sign for negative values, and speak-as tells screen readers how to announce the marker, for example as a number or as a bullet.
Four custom counter styles

The sixth item in the circled list shows the fallback at work: the fixed style ran out of symbols, so the browser used decimal for it. Custom styles work with counters too: content: counter(step, padded) prints 01, 02 and so on. The prefix and suffix are only added to list markers, so write any extra text into content yourself.

@counter-style has worked in all major browsers since 2023, when Safari added full support. A browser that doesn't know your style's name treats it like decimal, so lists still get ordinary numbers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which property creates a counter (or a new instance of it) on an element?

    counter-reset creates the counter and sets its starting value. counter-increment changes it, and the two functions display it.
  2. 2. Every heading shows "1" instead of 1, 2, 3. What is the most likely cause?

    Without a reset on a common ancestor, the browser creates a fresh counter on each element, starting at 0 and incrementing to 1.
  3. 3. What does counters(item, ".") produce for the third item inside the second item of a nested list?

    counters() joins every nested instance from outermost to innermost, so it prints 2.3.
  4. 4. Two rules on body say counter-reset: figure; and counter-reset: table;. What happens?

    Counter properties follow the normal cascade. Write counter-reset: figure table; in one declaration instead.
  5. 5. How do you display a counter as Roman numerals?

    The second argument of counter() (or the third of counters()) accepts any list style type.

Summary

  • Counters need a counter-reset on a container, a counter-increment on the counted elements, and counter() in content to show the value.
  • Optional numbers set a starting value or a step size, including negative steps.
  • counter(name, style) formats the number with any list style type, such as upper-roman.
  • counters(name, ".") prints nested instances, giving outline numbering like 1.2.3 to any depth.
  • Put all counter names in one declaration, because the cascade keeps only one value.

Next: Styling Tables, where you will turn raw data tables into something readable on any screen.