Introduction to CSS Counter Styles API

Mon Mar 20 2023

4 min read

CSS Counter Styles API is an incredibly useful tool for adding automatic numbering or labeling to elements in HTML and CSS.

Whether you want to number a series of items, label a list of subheadings, or create a unique style for your numbering system, this API can help you achieve your goal.

How does CSS Counter Style API work?

CSS Counter Styles API is a type of Web API that allows you to number or label elements in your HTML document automatically. We define a counter with a specific name and starting value and then increment or decrement that counter according to the CSS rules.

To use this API, first, define a counter with the counter-reset property, set its starting value, and then increment or decrement the counter as needed with the counter-increment property. You can also use the content property to display the counter's current value in your HTML content.

Syntax for defining counters

The syntax for defining CSS counters is as follows:

To define a counter:

css
counter-reset: counter-name initial-value;`
  • counter-name: The name of the counter you want to define.
  • initial-value: The starting value of the counter.

To increment or decrement a counter:

css
counter-increment: counter-name increment-value;
  • counter-name: The name of the counter you want to increment or decrement.
  • increment-value: The amount by which to increment or decrement the counter.

To display the current value of a counter:

css
content: counter(counter-name);
  • counter-name: The name of the counter you want to display.

Examples of CSS Counters Style API

  • Numbered Lists

One common use case for CSS Counter Style API is to create custom numbered lists. By default, HTML provides a limited set of list styles (such as square, disc, and circle). However, with this API, you can create custom numbering styles and apply them to any list.

For example, let's say you want to create a custom list style that uses Roman numerals instead of Arabic numerals. You could define a custom counter style for Roman numerals and apply it to a ol element using the counter-style property:

css
@counter-style roman {
system: cyclic;
symbols: "I" "II" "III" "IV" "V" "VI" "VII" "VIII" "IX" "X" "XI" "XII" "XIII" "XIV" "XV";
suffix: " ";
}
ol {
list-style-type: none;
counter-reset: my-counter;
counter-style: roman;
}
li::before {
content: counter(my-counter) ". ";
counter-increment: my-counter;
}
  • Custom Numbering Systems

To define a custom numbering system, you first define a custom counter style that specifies the symbols to use and the formatting options. For example, let's say you want to create a custom numbering system using emojis:

css
@counter-style emoji {
system: cyclic;
symbols: "😀" "😃" "😄" "😁" "😆" "😅" "😂" "🤣" "🥲" "😊";
suffix: " ";
}

Once you've defined a custom counter style, you can apply it to any element using the counter-style property. For example, you could apply the emoji counter style to a ol element as follows:

css
ol {
counter-reset: my-counter;
counter-style: emoji;
}
li::before {
content: counter(my-counter) ". ";
counter-increment: my-counter;
}

Custom Counter Styles

Custom counter styles are defined using the @counter-style rule, allowing you to create a new style with a specific name. Like normal counters, you can use this custom counter style with the counter-reset and counter-increment properties.

Syntax

The syntax for defining a custom counter style using the @counter-style rule is as follows:

css
@counter-style counter-name {
counter-style-properties;
}
  • counter-name: The name of the custom counter style you want to define.
  • counter-style-properties: The properties that define the behavior of the custom counter style.

Properties

You can use several properties to define the behavior of a custom counter style, including system, symbols, suffix, prefix, pad, and fallback.

Here are some examples of custom counter styles:

  1. Roman Numerals:
css
@counter-style roman {
system: upper-roman;
}

This custom counter style defines a numbering system that uses upper-case Roman numerals.

  1. Circles
css
@counter-style circle {
symbols: "\25CF";
}

This custom counter style defines a numbering system that uses black circles instead of numbers.

  1. Alphabets
css
@counter-style alphabets {
system: lower-alpha;
suffix: ".";
}

This custom counter style defines a numbering system that uses lower-case letters followed by a period.

Wrap up

CSS counter styles API provides the flexibility and controls you need to achieve your design goals, whether you need to create numbered lists, chapter and section headings, or completely custom numbering systems.

This API can help you create more visually appealing and interactive web pages that improve the user experience and make your content more engaging by incorporating them into your web development toolkit.