CSS Counters Tutorial: counter-reset, counter-increment And counter() (2026-27)

✅ What Are CSS Counters?

CSS counters are variables, maintained entirely by the browser, whose value can be incremented automatically based on how many times a CSS selector matches in your document. They let you generate custom, automatic numbering - for lists, headings, figures, or any repeating element - without manually typing numbers into your HTML or relying on JavaScript.

✅ counter-reset

counter-reset declares a named counter and sets its value - by default 0 - on the element where counting should begin (usually a parent container, like the ol or body).

/* Creates a counter named "item", starting at 0 */
ol {
  counter-reset: item;
}

/* You can also set a custom starting value */
ol.start-at-five {
  counter-reset: item 5;
}

✅ counter-increment

counter-increment increases the named counter's value - by default +1 - every time its selector matches, typically once per list item or heading.

You can also increment by a custom amount, or even count downward:

li { counter-increment: item 2; }   /* +2 each time */
li { counter-increment: item -1; }  /* counts DOWN  */

✅ The counter() Function

The counter() function displays a counter's current value as generated content - it only works inside the content property of a ::before or ::after pseudo-element.

✅ The counters() Function – Multi-Level Numbering

The counters() function (note the s) returns the values of a counter at every nesting level, joined by a separator string - exactly what you need for outline-style numbering like 1.1, 1.2, 2.1.

✅ Custom Counter Styles (Roman, Alpha, etc.)

Both counter() and counters() accept an optional second argument - any list-style-type keyword - to render the number in a different numbering system.

li::before { content: counter(item, upper-roman) ". "; }   /* I. II. III. */
li::before { content: counter(item, lower-alpha) ") "; }   /* a) b) c) */
li::before { content: counter(item, decimal-leading-zero) " - "; } /* 01 - 02 - */

✅ Automatic Heading & Section Numbering

A very common real-world pattern: number every heading of a certain level automatically, so the numbering never gets out of sync as sections are added or reordered.

✅ Step-by-Step Guides with Counters

Tutorial sites, recipe pages, and onboarding flows commonly use counters to build "Step 1 / Step 2 / Step 3" badges that never drift out of sync with the actual step order.

.tutorial-steps {
  list-style: none;
  counter-reset: tut-step;
}

.tutorial-steps li {
  counter-increment: tut-step;
  position: relative;
  padding-left: 40px;
  margin-bottom: 14px;
}

.tutorial-steps li::before {
  content: counter(tut-step);
  position: absolute;
  left: 0;
  top: 0;
  width: 26px;
  height: 26px;
  background: #0EA5E9;
  color: #fff;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: bold;
  font-size: 13px;
}

✅ Counter Scope & Nesting Rules

Each counter-reset creates a new, separate instance of that counter, scoped to the element it's declared on (and its descendants). This is what makes nested numbering and multiple independent lists work correctly on the same page.

/* Two SEPARATE counters, both named "item" */
ol.list-a { counter-reset: item; }  /* starts its own count at 0 */
ol.list-b { counter-reset: item; }  /* starts its own count at 0 too */

/* Without a counter-reset on .list-b,
   it would continue counting from .list-a instead! */

✅ Counter Functions – Reference Table

✅ Best Practices

✔️ 1) Always Pair counter-reset with counter-increment
A counter that's only incremented but never reset can behave inconsistently across browsers - always declare both explicitly.

✔️ 2) Use Descriptive Counter Names
Prefer counter-reset: section; over a vague name like counter-reset: c1; - future readers (including you) will thank you.

✔️ 3) Reset Scoped Counters on Every Independent List
If multiple separate lists should each start at 1, give each one its own counter-reset rather than relying on a single page-wide counter.

✔️ 4) Prefer counters() for Any Nested/Outline Numbering
Reaching for counter() on multi-level lists is a common mistake - use counters() whenever you need the full "1.2.3" style path.

✔️ 5) Remember Counters Only Render Inside Generated Content
counter() and counters() only work inside the content property of ::before/::after - they cannot be inserted as plain text content elsewhere.

✅ Common Mistakes to Avoid

✅ Complete Live Example

A documentation-style numbered outline combining multi-level counters() with custom styling:

✅ Try It Yourself – Interactive Editor

Edit the HTML and CSS below to experiment with CSS counters. Try switching between flat numbering, multi-level outlines, and step badges. The preview updates automatically.

✅ 🎨 Interactive Counter Playground

Choose a numbering style, separator, prefix/suffix text, and starting value to instantly preview your own custom CSS counter. Copy the generated CSS with one click.

✅ Practice – Yes / No Quiz

✅ Frequently Asked Questions (FAQ)