Before diving in, make sure you are comfortable with these ideas. If any of them are unfamiliar, read the short explanation provided below each.

What is a CSS Property?

A CSS property is an instruction you write in CSS to control how something looks or behaves. For example, color: red; is a property that makes text red.

What is ::before and ::after?

These are CSS pseudo-elements. Think of them as invisible "attachment zones" that exist just before or just after the content of an HTML element. You can insert generated text or symbols into those zones using the content property in CSS.

/* This inserts the word "Note: " before every paragraph */
p::before {
  content: "Note: ";
  color: blue;
}

Expected output in the browser:

Note: This is my paragraph text.

CSS counters use ::before and ::after to inject counter numbers into your page.

What is the content Property?

The content property only works inside ::before and ::after. It tells CSS what text or value to insert into that pseudo-element slot.

h2::before {
  content: "★ ";
}

This would place a star before every <h2> heading on the page.

The Big Idea

A CSS counter is like an invisible variable that CSS manages for you. You give it a name, tell it where to start, tell it when to count up, and then display its current value wherever you want.

Analogy: Imagine a sports scorekeeper. The scorekeeper starts at 0, adds 1 point every time a team scores, and shows the current total on a scoreboard. A CSS counter works the same way · it starts at a value you set, increases every time it encounters a matching HTML element, and displays the total at that element.

Why Do CSS Counters Exist? What Problem Do They Solve?

Without CSS counters, if you want numbered headings on a webpage, you have to type the numbers manually into your HTML:

<h2>1. Introduction</h2>
<h2>2. Setup</h2>
<h2>3. Usage</h2>
<h2>4. Advanced</h2>

The problem? If you later add a new section between "1. Introduction" and "2. Setup", you have to manually renumber every single heading after it. That is time-consuming, error-prone, and completely unnecessary.

With CSS counters, the browser handles ALL the numbering automatically. You just add or remove headings and the numbers update themselves.

The Four Key CSS Counter Tools

There are exactly four things you need to understand to use counters:

Let's explore each one in depth.

What It Does

counter-reset is how you declare (create) a counter. You write it on a parent element, and it resets (or initialises) the counter to a value you choose.

Syntax:

selector {
  counter-reset: counter-name starting-value;
}

• counter-name · You choose any name you like (no spaces). Examples: section, myCounter, chapter, step.
• starting-value · Optional. The number the counter begins at before it is first incremented. Default is 0.

Simple Example

body {
  counter-reset: section;
}

This creates a counter called section that starts at 0. It is placed on body so it applies to the whole page.

Thinking prompt: Why do we place counter-reset on the parent element rather than the element being counted? Because the parent is where the counter "lives". Child elements then increment it as the browser scans through them.

What It Does

counter-increment increases the counter's value. You place it on the element that you want to "trigger" a count increase.

Syntax:

selector {
  counter-increment: counter-name amount;
}

• counter-name · The same name you used in counter-reset.
• amount · Optional. How much to increase by. Default is 1. You can use negative values to count down.

Simple Example

h2 {
  counter-increment: section;
}

Every time the browser finds an <h2> element on the page, it increases the section counter by 1.

What happens if you do NOT use counter-increment? Nothing counts. The counter stays at 0 forever.

What It Does

counter() is a CSS function that reads the current value of a named counter and returns it as text. You use it inside the content property of a ::before or ::after pseudo-element.

Syntax:

selector::before {
  content: counter(counter-name);
}

You can also add text around it:

selector::before {
  content: "Section " counter(section) ": ";
}

Now let's combine all three tools into a complete working example.

Example 1 · Auto-Numbering Headings (Simplest Possible)

HTML:

<body>
  <h2>Introduction</h2>
  <h2>Setup</h2>
  <h2>Usage</h2>
  <h2>Advanced Topics</h2>
</body>

CSS:

/* Step 1: Create the counter on the parent element */
body {
  counter-reset: section;
}

/* Step 2: Increment the counter each time an h2 is found */
h2 {
  counter-increment: section;
}

/* Step 3: Display the counter value before each h2 */
h2::before {
  content: "Section " counter(section) " — ";
}

Expected Output in Browser:

Section 1 — Introduction
Section 2 — Setup
Section 3 — Usage
Section 4 — Advanced Topics

Line-By-Line Explanation

Thinking prompt: What would happen if we put counter-reset on h2 instead of body? The counter would reset to 0 every time a new <h2> is found · so every heading would show "Section 1". Try it and see!

Example 2 · Auto-Numbering with Custom Start Value

What if you want numbering to start at 5 instead of 1?

body {
  counter-reset: section 4;  /* Start at 4, so first increment gives 5 */
}

h2 {
  counter-increment: section;
}

h2::before {
  content: "Step " counter(section) ": ";
}

Expected Output:

Step 5: First heading
Step 6: Second heading
Step 7: Third heading

Why 4 not 5? Because counter-reset sets the value BEFORE the first increment. When the browser hits the first <h2>, it increments from 4 to 5, so the display starts at 5.

Example 3 · Counting by 2 (Increment Amount)

body {
  counter-reset: even;
}

p {
  counter-increment: even 2;
}

p::before {
  content: counter(even) ". ";
}

HTML:

<p>First paragraph</p>
<p>Second paragraph</p>
<p>Third paragraph</p>

Expected Output:

2. First paragraph
4. Second paragraph
6. Third paragraph

By default, counters display as decimal numbers (1, 2, 3...). But you can change this!

Syntax:

content: counter(counter-name, list-style-type);

Example · Roman Numeral Sections

body {
  counter-reset: chapter;
}

h2 {
  counter-increment: chapter;
}

h2::before {
  content: counter(chapter, upper-roman) ". ";
}

Expected Output:

I. Introduction
II. Setup
III. Usage
IV. Advanced Topics

The Concept

In a book, you have chapters and within each chapter you have sections:

Chapter 1
  1.1 First Section
  1.2 Second Section
Chapter 2
  2.1 First Section
  2.2 Second Section

This is called nested numbering. CSS counters can do this with multiple counter instances · one for the top level and one for the sub-level.

The Key Insight: counter-reset on a Child Resets for Each Parent

When you put counter-reset on an element, it creates a fresh instance of the counter each time that element appears. So if chapters reset the section counter, each new chapter gets its own section count starting from 0.

Example 4 · Two-Level Nested Counter (Chapter → Section)

HTML:

<body>
  <h1>Introduction</h1>
    <h2>What is CSS?</h2>
    <h2>Why CSS Matters</h2>
  <h1>Fundamentals</h1>
    <h2>Selectors</h2>
    <h2>Properties</h2>
    <h2>Values</h2>
  <h1>Advanced</h1>
    <h2>Flexbox</h2>
    <h2>Grid</h2>
</body>

CSS:

/* Level 1: Chapter counter on body */
body {
  counter-reset: chapter;
}

h1 {
  counter-increment: chapter;
  counter-reset: section;    /* Reset section counter for each new chapter */
}

h1::before {
  content: counter(chapter) ". ";
}

/* Level 2: Section counter */
h2 {
  counter-increment: section;
}

h2::before {
  content: counter(chapter) "." counter(section) " ";
  margin-left: 20px;
}

Expected Output:

1. Introduction
    1.1 What is CSS?
    1.2 Why CSS Matters
2. Fundamentals
    2.1 Selectors
    2.2 Properties
    2.3 Values
3. Advanced
    3.1 Flexbox
    3.2 Grid

Step-By-Step Breakdown

1. body { counter-reset: chapter; } · Creates the chapter counter (starts at 0)
2. h1 { counter-increment: chapter; } · Each <h1> adds 1 to chapter
3. h1 { counter-reset: section; } · Each <h1> ALSO resets section back to 0, so sections restart for every new chapter
4. h2 { counter-increment: section; } · Each <h2> adds 1 to section
5. h2::before { content: counter(chapter) "." counter(section) " "; } · Displays "chapter.section" format

This is the key to nested counters: you put BOTH counter-increment and counter-reset on the parent-level element. That parent counts itself UP, while also resetting the child counter.

When to Use counters() Instead of counter()

When your list items can be arbitrarily deeply nested (like an outline that could go 3, 4, or 5 levels deep), using multiple separate counter names becomes complex. The counters() function handles this elegantly by automatically tracking ALL levels of nesting and joining them with a separator you provide.

Syntax:

content: counters(counter-name, "separator");

• counter-name · The same counter name used at every level
• "separator" · The character(s) between each level (e.g., "." or " - ")

How It Works

The magic is that CSS creates a new scope of the same-named counter for each nested list. counters() collects all the values from the outermost to the innermost scope and joins them with your separator.

Example 5 · Deeply Nested Outline List

HTML:

<ol>
  <li>First item
    <ol>
      <li>Sub item A</li>
      <li>Sub item B
        <ol>
          <li>Deep item i</li>
          <li>Deep item ii</li>
        </ol>
      </li>
      <li>Sub item C</li>
    </ol>
  </li>
  <li>Second item</li>
  <li>Third item
    <ol>
      <li>Sub item A</li>
      <li>Sub item B</li>
    </ol>
  </li>
</ol>

CSS:

/* Remove default list numbering */
ol {
  list-style: none;
  counter-reset: outline;
}

li {
  counter-increment: outline;
}

li::before {
  content: counters(outline, ".") " ";
}

Expected Output:

1 First item
  1.1 Sub item A
  1.2 Sub item B
    1.2.1 Deep item i
    1.2.2 Deep item ii
  1.3 Sub item C
2 Second item
3 Third item
  3.1 Sub item A
  3.2 Sub item B

Why This Works

• Each <ol> element triggers a counter-reset: outline (because every ol has that rule)
• This creates a new, fresh scope of the outline counter
• Each <li> increments the outline counter in its own scope
• counters(outline, ".") reads all the nested scope values from outside to inside and joins them with "."

Thinking prompt: What would change if you used "/" as the separator instead of "."? The output would be 1/2/3 style numbering instead of 1.2.3. Try it!

Mistake 1 · Forgetting counter-reset

/* WRONG — counter was never created */
h2 {
  counter-increment: section;
}
h2::before {
  content: counter(section);
}

Problem: Without counter-reset, the counter does not exist. The browser may still try to display something, but the behaviour is undefined.

Fix: Always declare the counter with counter-reset on a parent element first.

/* CORRECT */
body {
  counter-reset: section;   /* Create it here */
}
h2 {
  counter-increment: section;
}
h2::before {
  content: counter(section);
}

Mistake 2 · Using content Without ::before or ::after

/* WRONG — content only works in pseudo-elements */
h2 {
  content: counter(section);
}

Problem: The content property has no effect on regular HTML elements. It only works inside ::before and ::after.

Fix: Always use ::before or ::after:

h2::before {
  content: counter(section) ". ";
}

Mistake 3 · Forgetting to Reset the Child Counter in Nested Counters

/* WRONG — sections never reset between chapters */
body { counter-reset: chapter; }
h1 { counter-increment: chapter; }
h2 { counter-increment: section; }   /* <-- section never resets! */

Problem: The section counter keeps going up across all chapters (1, 2, 3, 4, 5...) instead of resetting for each chapter (1.1, 1.2, 2.1, 2.2...).

Fix: Reset the child counter on the parent element:

h1 {
  counter-increment: chapter;
  counter-reset: section;    /* Reset sections for every new chapter */
}

Mistake 4 · Using counter() Instead of counters() for Nested Lists

/* WRONG — only shows the current level number */
ol { counter-reset: item; }
li { counter-increment: item; }
li::before {
  content: counter(item) ". ";
}

Problem: This only shows the number at the current nesting level (1, 2, 3 everywhere) · it does NOT show the full path like "1.2.3".

Fix: Use counters() with a separator:

li::before {
  content: counters(item, ".") ". ";
}

Mistake 5 · Confusing Start Value in counter-reset

/* WRONG — if you want to start at 1, don't set reset to 1 */
body {
  counter-reset: section 1;
}
h2 {
  counter-increment: section;
}

Problem: The first <h2> will display 2 because the counter starts at 1 and then gets incremented to 2.

Fix: Set counter-reset to one LESS than your desired start number:

/* To start at 1: reset to 0 (the default) */
body {
  counter-reset: section;   /* starts at 0, first increment = 1 */
}

/* To start at 5: reset to 4 */
body {
  counter-reset: section 4;  /* starts at 4, first increment = 5 */
}

Mistake 6 · Forgetting list-style: none When Replacing <ol> Numbering

/* PROBLEM — browser shows both default numbers AND your counter */
ol {
  counter-reset: item;
}
li::before {
  content: counter(item) ". ";
  counter-increment: item;
}

Problem: The <ol> still shows its built-in 1, 2, 3 numbering, AND your custom counter also shows. You get double numbers.

Fix: Remove the default list numbering:

ol {
  list-style: none;
  counter-reset: item;
}

CSS counters are used widely in professional web development:

Documentation sites · Technical documentation like developer guides, API references, and user manuals use counters to auto-number sections and API endpoints.

Legal and contract documents · Law firms and contract template platforms use counters for clause numbering (1, 1.1, 1.1.1).

Academic papers and theses · Research platforms use counters to number figures, tables, equations, and sections.

E-learning platforms · Course outlines, lesson numbering, and progress tracking on sites like Coursera use counter-like systems.

Recipe sites · Step-by-step cooking instructions with auto-numbered steps.

Terms and conditions pages · Large legal T&C pages with numbered clauses and sub-clauses.

Print stylesheets · When printing webpages, CSS counters are used to add page numbers and section references in print media queries.