Introduction to @Counter Style
CSS provides a rich set of predefined counter styles for styling lists and counters in generated content, but sometimes you need something more specific. The @counter-style at-rule gives you complete control to define custom counter styles that go beyond the browser defaults, enabling unique visual treatments for ordered lists, navigation menus, and any element requiring numbered or symbolic markers.
Why Custom Counter Styles Matter
In modern web development, visual consistency across interfaces has become essential for brand identity and user experience. Default browser list markers--the standard bullets, discs, and numbered sequences--often clash with custom design systems. Custom counter styles allow developers to align list markers with brand typography, use symbolic markers that convey meaning, create numbered sequences for specialized content, and develop multilingual counter representations.
When combined with CSS color techniques, custom counter styles help create cohesive, branded visual experiences across your entire website.
Browser Support and Baseline Status
The @counter-style at-rule reached Baseline status in September 2023, meaning it works across the latest devices and browser versions. This widespread support makes it a reliable choice for production use.
Basic Syntax and Structure
A @counter-style rule is identified by a counter style name and contains descriptors that define how the counter value converts into a string representation.
Counter Style Name
The counter style name is specified as a case-sensitive custom identifier without quotes. This name must not be equal to none or other CSS-wide keywords. Additionally, the name cannot match case-insensitive values of the list-style-type property, including decimal, disc, square, circle, disclosure-open, and disclosure-closed. These reserved names are non-overridable and serve as fallback styles.
@counter-style thumbs {
system: cyclic;
symbols: "\1F44D";
suffix: " ";
}
Custom counter styles work alongside other CSS layout techniques like flexbox and CSS columns to create sophisticated list layouts and navigation components.
Core Descriptors
The @counter-style at-rule relies on several descriptors to define the counter behavior.
System Descriptor
The system descriptor specifies the algorithm used to convert the integer value of a counter into its string representation:
- cyclic: Cycles through the symbols indefinitely, useful for simple bullet-like markers
- numeric: Interprets symbols as digits in a place-value numbering system
- alphabetic: Treats symbols as alphabetic characters
- symbolic: Produces one or more copies of symbols for each counter value
- additive: Uses additive tuples for constructing counter representations
- fixed: Defines a finite set of symbols that repeat after exhaustion
Symbols Descriptor
The symbols descriptor specifies the symbols used for marker representations. These symbols can contain strings, images, or custom identifiers. Required for cyclic, numeric, alphabetic, symbolic, and fixed systems.
Additive Symbols Descriptor
For additive counter systems like Roman numerals, the additive-symbols descriptor defines the weighted symbol tuples listed by weight in descending order.
@counter-style roman {
system: additive;
additive-symbols: 1000 M, 900 CM, 500 D, 400 CD, 100 C, 90 XC,
50 L, 40 XL, 10 X, 9 IX, 5 V, 4 IV, 1 I;
}
For complex counter implementations, consider combining these with CSS text shadow effects to create visually distinctive list markers that stand out.
Supporting Descriptors
Beyond the core descriptors, several supporting descriptors customize the appearance and behavior of counter styles.
Negative Descriptor
The negative descriptor specifies symbols to prepend or append when the value is negative, useful in mathematical or financial contexts.
Prefix and Suffix Descriptors
The prefix and suffix descriptors add symbols before or after the marker representation. These enable formatting like parenthesized numbers or period-separated lists.
Range Descriptor
The range descriptor defines values over which the counter style is applicable, with fallback to the fallback style for out-of-range values.
Pad Descriptor
The pad descriptor ensures minimum length by padding with specified characters, creating zero-padded numbers like "01", "02", "03".
Speak-As Descriptor
The speak-as descriptor describes how speech synthesizers should announce the counter style, ensuring accessibility for custom symbols or numbering systems.
Fallback Descriptor
The fallback descriptor specifies the counter name used when the system cannot construct the representation, eventually defaulting to decimal.
For accessibility-focused implementations, pair these descriptors with our guide on accessible web applications and widgets.
Practical Examples
Custom Bullet Style
@counter-style thumbs {
system: cyclic;
symbols: "\1F44D";
suffix: " ";
}
This creates a thumbs-up emoji marker, suitable for approval lists or positive item collections.
Chapter Numbering
@counter-style chapter {
system: extends decimal;
suffix: ". ";
}
ol {
list-style-type: chapter;
}
Extends decimal while changing the suffix for chapter-style numbering.
Zero-Padded Numbers
@counter-style padded-numbers {
system: extends decimal;
pad: 3 "0";
}
Creates "001", "002", "003" instead of "1", "2", "3" for aligned numbering.
For creating sophisticated list layouts, these counter styles can be combined with CSS display properties for advanced formatting options.
CSS Counters Properties Integration
The @counter-style at-rule works alongside several CSS properties:
- counter-increment: Specifies how much a counter increments for each element occurrence
- counter-reset: Creates or resets a named counter
- counter-set: Sets a counter to a specific value without affecting increment
- list-style-type: References a custom counter style by name
The ::marker Pseudo-Element
The ::marker pseudo-element represents the marker box of a list item. This can be styled with content, font-size, color, and other properties, though browser support varies for certain styling options.
When building responsive web applications, proper counter styling contributes to polished, professional interfaces that enhance user experience across all device sizes.
Accessibility Considerations
When implementing custom counter styles, accessibility should remain a primary concern:
- Use the
speak-asdescriptor to ensure screen readers announce custom symbols correctly - Test custom counter styles with assistive technologies
- Consider text alternatives where symbols might be confusing
- For users with CSS disabled, ensure the counter style degrades gracefully
The speak-as descriptor provides built-in support for screen readers, ensuring custom symbols or numbering systems are announced correctly to assistive technology users. Following web accessibility guidelines ensures your custom counters work for all users.
Performance and Best Practices
Performance
Custom counter styles defined with @counter-style are parsed once and reused throughout the document, making them performant for repeated use.
Best Practices
- Define counter styles at the root level or in a central stylesheet
- Reuse existing counter style definitions rather than creating similar styles
- Choose descriptive names that indicate purpose or visual treatment
- Document intended use and special behaviors for future maintainability
- Test across browsers, especially for complex counter systems
Conclusion
The @counter-style at-rule opens new possibilities for customizing list markers and counter representations in CSS. From simple emoji bullets to complex multilingual numbering systems, this feature provides flexibility for modern design systems while maintaining accessibility and browser compatibility. When working with a professional web development team, you can leverage these CSS capabilities to create polished, consistent interfaces that reflect your brand identity.