Some Things You Might Not Know About Custom Counter Styles

by: Geoff Graham
Thu, 23 Jan 2025 17:21:15 +0000

I was reading through Juan’s recent Almanac entry for the @counter-style at-rule and I’ll be darned if he didn’t uncover and unpack some extremely interesting things that we can do to style lists, notably the list marker. You’re probably already aware of the ::marker pseudo-element. You’ve more than likely dabbled with custom counters using counter-reset and counter-increment. Or maybe your way of doing things is to wipe out the list-style (careful when doing that!) and hand-roll a marker on the list item’s ::before pseudo.

But have you toyed around with @counter-style? Turns out it does a lot of heavy lifting and opens up new ways of working with lists and list markers.

You can style the marker of just one list item

This is called a “fixed” system set to a specific item.

@counter-style style-fourth-item {
  system: fixed 4;
  symbols: "💠";
  suffix: " ";
}

li {
  list-style: style-fourth-item;
}

You can assign characters to specific markers

If you go with an “additive” system, then you can define which symbols belong to which list items.

@counter-style dice {
  system: additive;
  additive-symbols: 6 "⚅", 5 "⚄", 4 "⚃", 3 "⚂", 2 "⚁", 1 "⚀";
  suffix: " ";
}

li {
  list-style: dice;
}

Notice how the system repeats once it reaches the end of the cycle and begins a new series based on the first item in the pattern. So, for example, there are six sides to typical dice and we start rolling two dice on the seventh list item, totaling seven.

You can add a prefix and suffix to list markers

A long while back, Chris showed off a way to insert punctuation at the end of a list marker using the list item’s ::before pseudo:

ol {
  list-style: none;
  counter-reset: my-awesome-counter;

  li {
    counter-increment: my-awesome-counter;

    &::before {
      content: counter(my-awesome-counter) ") ";
    }
  }
}

That’s much easier these days with @counter-styles:

@counter-style parentheses {
  system: extends decimal;
  prefix: "(";
  suffix: ") ";
}

You can style multiple ranges of list items

Let’s say you have a list of 10 items but you only want to style items 1-3. We can set a range for that:

@counter-style single-range {
  system: extends upper-roman;
  suffix: ".";
  range: 1 3;
}

li {
  list-style: single-range;
}

We can even extend our own dice example from earlier:

@counter-style dice {
  system: additive;
  additive-symbols: 6 "⚅", 5 "⚄", 4 "⚃", 3 "⚂", 2 "⚁", 1 "⚀";
  suffix: " ";
}

@counter-style single-range {
  system: extends dice;
  suffix: ".";
  range: 1 3;
}

li {
  list-style: single-range;
}

Another way to do that is to use the infinite keyword as the first value:

@counter-style dice {
  system: additive;
  additive-symbols: 6 "⚅", 5 "⚄", 4 "⚃", 3 "⚂", 2 "⚁", 1 "⚀";
  suffix: " ";
}

@counter-style single-range {
  system: extends dice;
  suffix: ".";
  range: infinite 3;
}

li {
  list-style: single-range;
}

Speaking of infinite, you can set it as the second value and it will count up infinitely for as many list items as you have.

Maybe you want to style two ranges at a time and include items 6-9. I’m not sure why the heck you’d want to do that but I’m sure you (or your HIPPO) have got good reasons.

@counter-style dice {
  system: additive;
  additive-symbols: 6 "⚅", 5 "⚄", 4 "⚃", 3 "⚂", 2 "⚁", 1 "⚀";
  suffix: " ";
}

@counter-style multiple-ranges {
  system: extends dice;
  suffix: ".";
  range: 1 3, 6 9;
}

li {
  list-style: multiple-ranges;
}

You can add padding around the list markers

You ever run into a situation where your list markers are unevenly aligned? That usually happens when going from, say, a single digit to a double-digit. You can pad the marker with extra characters to line things up.

/* adds leading zeroes to list item markers */
@counter-style zero-padded-example {
  system: extends decimal;
  pad: 3 "0";
}

Now the markers will always be aligned… well, up to 999 items.

That’s it!

I just thought those were some pretty interesting ways to work with list markers in CSS that run counter (get it?!) to how I’ve traditionally approached this sort of thing. And with @counter-style becoming Baseline “newly available” in September 2023, it’s well-supported in browsers.

---

Some Things You Might Not Know About Custom Counter Styles originally published on CSS-Tricks, which is part of the DigitalOcean family. You should get the newsletter.