CSS @counter-style At-Rule

The @counter-style at-rule defines custom counter styles for ordered lists, unordered lists, and other CSS-generated markers. It allows you to control the symbols, numbering system, prefixes, suffixes, and fallback behavior used when displaying counters.

@counter-style Syntax

@counter-style custom-name {
  system: cyclic;
  symbols: "★" "☆";
  suffix: " ";
}

The at-rule begins with @counter-style, followed by a name and a declaration block containing counter-style descriptors.

The name identifies the custom style and can be used with properties such as list-style-type. The descriptors determine how counter values are represented.

Custom counter-style names cannot use reserved counter-style names such as decimal, disc, or none.

How @counter-style Works

Browsers provide built-in list styles such as decimal numbers, letters, and bullet symbols. The @counter-style at-rule allows you to define additional styles.

First, create a named counter style. Then assign that name to a list using the list-style-type property.

@counter-style stars {
  system: cyclic;
  symbols: "★" "☆";
  suffix: " ";
}
ul {
  list-style-type: stars;
}

The list markers alternate between filled and outlined stars. The cyclic system repeats the supplied symbols as the counter values increase.

Custom counter styles can also be used with the counter() and counters() functions to format generated content.

@counter-style Descriptors

The following descriptors control how a custom counter style displays its values.

Descriptor	Description
`system`	Defines the algorithm used to generate counter representations.
`symbols`	Provides the symbols used by the selected numbering system.
`additive-symbols`	Defines weighted symbols for an additive numbering system.
`negative`	Defines symbols placed around negative counter values.
`prefix`	Adds a symbol or string before each counter representation.
`suffix`	Adds a symbol or string after each counter representation.
`range`	Specifies the counter values that the style can represent.
`pad`	Adds leading symbols to reach a minimum representation length.
`fallback`	Identifies another counter style to use when a value cannot be represented.
`speak-as`	Specifies how counter representations should be spoken by supporting speech systems.

The descriptors available depend on the selected system. For example, additive-symbols is used with the additive system rather than symbols.

Counter Systems

The system descriptor determines how counter values are converted into symbols.

Value	Description
`cyclic`	Repeats the supplied symbols in a cycle.
`numeric`	Uses symbols as digits in a positional numbering system.
`alphabetic`	Uses symbols in an alphabetic sequence, similar to a, b, c, ... aa, ab.
`symbolic`	Repeats symbols as needed to represent larger positive values.
`additive`	Combines weighted symbols to represent counter values.
`fixed`	Assigns symbols to a fixed sequence of counter values.
`extends`	Builds on an existing counter style while allowing selected descriptors to be changed.

Numeric Counter Style

@counter-style binary {
  system: numeric;
  symbols: "0" "1";
  suffix: ". ";
}

The numeric system treats the symbols as digits. This example represents counter values using binary numbers.

Fixed Counter Style

@counter-style priorities {
  system: fixed;
  symbols: "High" "Medium" "Low";
  suffix: ": ";
  fallback: decimal;
}

The fixed system assigns the three symbols to counter values 1, 2, and 3. Values outside that range use the decimal fallback.

Using Custom Counter Styles

After defining a counter style, use its name as the value of list-style-type.

@counter-style arrows {
  system: cyclic;
  symbols: "➜";
  suffix: " ";
}
.feature-list {
  list-style-type: arrows;
}

The .feature-list elements display arrow markers instead of the browser's default bullets.

You can also use a custom style with the counter() function.

@counter-style steps {
  system: extends decimal;
  prefix: "Step ";
  suffix: ": ";
}
.instructions {
  counter-reset: step;
}
.instructions p {
  counter-increment: step;
}
.instructions p::before {
  content: counter(step, steps);
}

This example generates labels such as Step 1: and Step 2: before the paragraphs.

@counter-style Example

The following example creates a custom star marker for a list. The cyclic system repeats the same symbol for each item.

@counter-style star-list {
  system: cyclic;
  symbols: "★";
  suffix: " ";
}
.custom-list {
  list-style-type: star-list;
  padding-left: 28px;
}
.custom-list li {
  margin-bottom: 6px;
}

The custom list uses a star instead of a standard bullet marker.

Play in Editor

Browser Support

The @counter-style at-rule is widely supported in modern browsers. Some descriptors, including speak-as, have more limited support. Visit Can I Use? and search for CSS @counter-style to check compatibility.

Specifications

The @counter-style at-rule is defined in the CSS Counter Styles Level 3 specification, which describes custom counter systems, descriptors, and formatting behavior.

CSS Counter Styles Level 3