symbols() | CSS-Tricks

The CSS symbols() function defines a counter style without using the @counter-style at-rule. Think of the function as a slimmed-down version of the rule with fewer features, but less configuration. It can be used inside the list-style-type property and the counter() and counters() functions.

ul {
  list-style: symbols(cyclic "🥬");
}

The symbols at-rule is defined in the CSS Counter Styles Level 3 specification.

Syntax

symbols() = symbols( <symbols-type>? [ <string> | <image> ]+ )
<symbols-type> = cyclic | numeric | alphabetic | symbolic | fixed

Arguments

/* cyclic */
list-style: symbols(cyclic "🔸" "🔹");

/* numeric */
list-style: symbols(numeric "0" "1");

/* alphabetic */
list-style: symbols(alphabetic "A" "B" "C");

/* symbolic (Default) */
list-style: symbols(symbolic "🟥" "🟨" "🟦");
list-style: symbols("🟥" "🟨" "🟦");

/* fixed */
list-style: symbols(fixed "✳️" "2" "✳️");

<symbols-type>:
- cyclic: repeats the characters until the list is over.
- numeric: uses the characters to create a numeric system (binary, trinary, hexadecimal, etc.), using the first character as 0. It needs at least two characters to work.
- alphabetic: uses the characters to create an alphabetic system. It’s similar to numeric, but uses 1 as the first character. It also needs at least two characters to work.
- symbolic: goes through the characters repeating them on each iteration.
- fixed: writes the characters until there aren’t more, without repeating them.
[ <string> | <image> ] A string or image used to construct the counter style. Image support is scarce, so most of the time we use strings. Unlike the @counter-style‘s symbols descriptor, the symbols() function doesn’t allow a <custom-ident>.

The arguments in the symbols() function are space-separated. No commas!

What are the defaults?

The symbols() function defines an anonymous counter style, which still has the same features as a @counter-style even if we can’t change them. It brings the following by default:

system: symbolic (if <symbols-type> wasn’t defined)
prefix: "" (empty string)
suffix: " " (space)
range: auto
fallback: decimal
negative: "-" (hyphen-minus)
pad: 0 ""
speak-as: of auto.

The symbols value are the provided <string>s or <image>s.

Basic usage

The symbols() function takes a space-separated (not comma-separated) list of arguments: starting with the <symbols-type> and then the characters we need. For example, to write a counter style that uses a binary system, we would start writing the type (numeric), and the required characters ("0" and "1"):

ol {
  list-style: symbols(numeric "0" "1");
}

Note the characters enclosed as strings, and not numbers.

If instead, we used @counter-style, the output would be considerably longer but we could use it for different counters:

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

.binary {
  list-style-type: binary-example;
}

#code {
  list-style-type: binary-example;
}

So, symbols() is ideal if we need to define a simple counter style for a one-off use case, as its more streamlined than @counter-styles by requiring less code and configuration.

Usage with `counter()` and `counters()`

The symbols() function can be used inside the counter() and counters() functions whenever we need to style a custom counter. The following example creates a decimal representation using circled numbers as numeric symbols:

ol {
  counter-reset: item;

  li {
    counter-increment: item 2;
  }

  li::marker {
    content: counter(item, symbols(numeric "⓪" "①" "②" "③" "④" "⑤" "⑥" "⑦" "⑧" "⑨")) ". ";
  }
}