Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท At-rules

The @counter-style at-rule

Reference for the CSS @counter-style at-rule: define your own counter styles with symbols, systems, suffixes and ranges, and use them in lists.

The @counter-style at-rule lets you define your own numbering or bullet style. Built-ins such as decimal, lower-roman and disc are all counter styles; this rule makes new ones, which you can use in list-style-type, in counter() and counters(), and in ::marker content.

A counter style is made of a system (how numbers map to symbols) and the symbols themselves, plus optional extras like a prefix, a suffix and a range of numbers it can handle.

CSS
@counter-style thumbs {
  system: cyclic;
  symbols: "๐Ÿ‘";
  suffix: " ";
}

Try it

Three custom list styles

Syntax

CSS
@counter-style <name> {
  system: cyclic | numeric | alphabetic | symbolic | additive | fixed <int>? | extends <name>;
  symbols: <symbol>+;
  additive-symbols: <weight> <symbol>#;
  negative: <symbol> <symbol>?;
  prefix: <symbol>;
  suffix: <symbol>;
  range: [<int> | infinite]{2}# | auto;
  pad: <int> <symbol>;
  fallback: <counter-style-name>;
  speak-as: auto | bullets | numbers | words | spell-out | <name>;
}

symbols is required for most systems; additive-symbols for additive. The default suffix is ". ".

Values

Syntax and arguments Description
system: cyclic Repeats the symbols forever; good for bullets.
system: numeric Positional numbers using the symbols as digits.
system: alphabetic a, b, ... z, aa, ab; needs at least two symbols.
system: symbolic Repeats symbols more times for bigger numbers (*, **, ***).
system: additive Weighted symbols, like Roman numerals.
system: fixed 5 Fixed list, starting at 5; then falls back.
system: extends decimal Start from an existing style and change parts of it.
range: 1 99 Numbers this style can represent; others use the fallback.
pad: 2 "0" Minimum length, padded with the symbol.

Usage notes

  • Use it with list-style-type (or the list-style shorthand) and in content: counter(name, style).
  • Quote symbols that are not valid identifiers; emoji and punctuation need quotes.
  • extends is the easy path for small variations: system: extends decimal; suffix: " - ";.
  • Fallback. When a number is outside range or the style cannot produce it, the fallback style (default decimal) is used.
  • Accessibility. Screen readers may speak the symbols; choose speak-as when a marker is purely decorative or meaningful as a number.
  • Name: must not be one of the predefined styles such as decimal or disc; the name is case-sensitive.
  • Predefined alternatives. list-style-type accepts a string directly (list-style-type: "- ") for simple bullets.

Browser support

Supported in Chrome and Edge 91, Firefox 33 and Safari 17, so it is available in current browsers; older Safari versions ignore the rule.