CSS symbols() Function

CSS symbols() Function

The CSS symbols() function defines an anonymous counter style using a sequence of custom symbols.

It is commonly used with list-style-type to customize list markers without creating a separate @counter-style rule. It can also be used with the counter() and counters() functions to format generated counter values.

Syntax

symbols(symbols)
symbols(system symbols)

The symbols() function accepts an optional symbol system followed by one or more symbols.

Examples:

list-style-type: symbols("*");
list-style-type: symbols("★" "☆");
list-style-type: symbols(cyclic "●" "○");
list-style-type: symbols(numeric "0" "1");
list-style-type: symbols(alphabetic "A" "B" "C");
list-style-type: symbols(symbolic "*" "†" "‡");
list-style-type: symbols(fixed "One" "Two" "Three");

If the system is omitted, symbolic is used by default.

The system keyword must appear before the symbols.

The function creates an anonymous counter style that can be used directly in a supported CSS property or function.

Parameters

The symbols() function accepts an optional system keyword and a required list of symbols.

Symbols are separated by spaces rather than commas.

For example:

list-style-type: symbols(cyclic "A" "B" "C");

This creates a repeating sequence of the letters A, B, and C.

Symbols can include ordinary text, Unicode characters, and supported CSS image values.

Symbol Systems

The optional system keyword determines how the supplied symbols are used to represent counter values.

Cyclic System

list-style-type: symbols(cyclic "●" "○");

The markers alternate between filled and hollow circles.

Numeric System

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

The symbols represent binary digits, producing values such as 1, 10, 11, and 100.

Alphabetic System

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

The sequence progresses through A, B, C, AA, AB, AC, BA, and so on.

Symbolic System

list-style-type: symbols(symbolic "*" "†");

The sequence begins with *, †, **, ††, ***, and †††.

Fixed System

list-style-type: symbols(fixed "First" "Second" "Third");

The first three counter values use the supplied strings. Values outside the defined range use the counter style's fallback.

How It Works

The symbols() function creates a counter style directly where it is needed.

For example:

ol {
  list-style-type: symbols(cyclic "◆" "◇");
}

The browser assigns the symbols to the list items according to their counter values.

For five items, the markers follow this sequence:

The function changes how the counter value is displayed. It does not change the actual counter value or the order of the list items.

Different symbol systems can produce different marker sequences from the same symbols.

Symbol Types

The symbols() function supports string symbols and image symbols.

Text Symbols

list-style-type: symbols(cyclic "Yes" "No");

Each quoted string is treated as a single symbol, including strings containing spaces.

Unicode Symbols

list-style-type: symbols(cyclic "★" "☆" "◆");

Unicode characters can create decorative list markers without additional images.

Image Symbols

list-style-type: symbols(cyclic url("marker-one.svg") url("marker-two.svg"));

Image values can also be used as symbols. The image resources must be available for the markers to display correctly.

For accessible content, choose symbols that remain understandable and do not rely solely on decorative differences to communicate important information.

Using list-style-type

The most common use of symbols() is with the list-style-type property.

For example:

ul {
  list-style-type: symbols(cyclic "★" "☆");
}

The first list item uses a filled star, the second uses an outlined star, and the sequence repeats.

Because symbols() defines the counter style directly, there is no need to declare a separate @counter-style rule.

The function can be applied to a specific list without affecting other lists:

.custom-list {
  list-style-type: symbols(cyclic "✓" "◆" "●");
}

Using Counter Functions

The symbols() function can also be used as a counter style within the counter() and counters() functions.

Using counter()

.item::before {
  content: counter(item-number, symbols(cyclic "◆" "◇")) " ";
}

This formats the named counter using alternating symbols.

Using counters()

.item::before {
  content: counters(section, ".", symbols(numeric "0" "1"));
}

This formats counter values from nested counter scopes using binary digits separated by periods.

These functions require counters to be established through the appropriate CSS counter properties or list behavior.

symbols() vs. @counter-style

Both symbols() and @counter-style can create custom counter representations, but they serve different purposes.

For a simple list, symbols() provides a compact solution:

ul {
  list-style-type: symbols(cyclic "◆" "◇");
}

For a reusable named style with more configuration options, use @counter-style:

@counter-style custom-diamonds {
  system: cyclic;
  symbols: "◆" "◇";
  suffix: " ";
}
ul {
  list-style-type: custom-diamonds;
}

Use symbols() for simple, local counter styles and @counter-style when greater customization or reuse is needed.

Example

The following example creates a list with custom star markers using the default symbolic system.

HTML:

<ol class="symbols-demo">
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <li>Fourth item</li>
  <li>Fifth item</li>
</ol>

CSS:

.symbols-demo {
  list-style-type: symbols("★" "☆");
  padding-left: 50px;
}
.symbols-demo li {
  padding: 5px 0;
}
.symbols-demo li::marker {
  color: #2e86c1;
}

Because no system keyword is specified, the function uses symbolic.

The markers progress through ★, ☆, ★★, ☆☆, and ★★★.

The ::marker pseudo-element changes the marker color without affecting the list text.

Cyclic Symbols Example

The following example uses the cyclic system to alternate between three markers.

HTML:

<ul class="symbols-cyclic">
  <li>HTML</li>
  <li>CSS</li>
  <li>JavaScript</li>
  <li>Accessibility</li>
  <li>Responsive Design</li>
  <li>Browser Testing</li>
</ul>

CSS:

.symbols-cyclic {
  list-style-type: symbols(cyclic "●" "◆" "■");
  padding-left: 45px;
}
.symbols-cyclic li {
  padding: 5px 0;
}
.symbols-cyclic li::marker {
  color: #16a085;
}

The first three items use ●, ◆, and ■. The sequence repeats for the remaining items.

Unlike the symbolic system, the cyclic system does not increase the number of repeated characters as counter values increase.

Alphabetic Symbols Example

The following example uses the alphabetic system with three letters.

HTML:

<ol class="symbols-alphabetic">
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
  <li>Item four</li>
  <li>Item five</li>
  <li>Item six</li>
</ol>

CSS:

.symbols-alphabetic {
  list-style-type: symbols(alphabetic "A" "B" "C");
  padding-left: 45px;
}
.symbols-alphabetic li {
  padding: 5px 0;
}
.symbols-alphabetic li::marker {
  color: #8e44ad;
}

The markers are A, B, C, AA, AB, and AC.

The alphabetic system builds longer representations when the counter exceeds the number of available symbols.

Generated Counter Example

The following example combines symbols() with the counter() function to generate custom markers using a CSS counter.

HTML:

<div class="symbols-counter-demo">
  <p class="symbols-counter-item">Create the HTML structure</p>
  <p class="symbols-counter-item">Add the CSS styles</p>
  <p class="symbols-counter-item">Test the layout</p>
  <p class="symbols-counter-item">Review accessibility</p>
</div>

CSS:

.symbols-counter-demo {
  counter-reset: task;
}
.symbols-counter-item {
  counter-increment: task;
  margin: 0;
  padding: 8px 0;
}
.symbols-counter-item::before {
  content: counter(task, symbols(cyclic "◆" "◇")) " ";
  color: #2e86c1;
  font-weight: bold;
  margin-right: 8px;
}

The counter-reset property initializes the counter, and counter-increment increases its value for each paragraph.

The counter() function formats each value using the anonymous cyclic style created by symbols().

For meaningful sequences, use an HTML ordered list when possible. CSS-generated content should not replace appropriate semantic markup.

Common Uses

The symbols() function is useful for customizing counter representations without defining a named counter style.

• Custom list markers: Replace standard bullets or numbers with decorative symbols.
• Alternating markers: Repeat a sequence of symbols using the cyclic system.
• Alphabetic numbering: Create custom letter-based counter sequences.
• Numeric systems: Display counter values using a custom set of digits.
• Generated content: Format CSS counters inside pseudo-elements.
• Decorative lists: Use stars, diamonds, circles, or other Unicode symbols.
• Local counter styles: Define a counter style directly where it is used.

For example:

.feature-list {
  list-style-type: symbols(cyclic "✓");
}

Every list item displays a checkmark marker.

Limitations

The symbols() function has several requirements and limitations.

• It must contain at least one symbol.
• The numeric and alphabetic systems require at least two symbols.
• Only the supported system keywords can be used.
• The system keyword must appear before the symbol list.
• Symbols are separated by whitespace, not commas.
• It creates an anonymous counter style rather than a named reusable style.
• It cannot define custom prefixes, suffixes, ranges, or fallback rules.
• The fixed system has a limited range based on the number of supplied symbols.
• Image symbols depend on the availability of their image resources.
• Symbol appearance can vary according to the available fonts and browser rendering.
• It does not change the underlying counter value or document order.

Valid and Invalid Values

These declarations are valid:

list-style-type: symbols("*");
list-style-type: symbols(cyclic "●" "○");
list-style-type: symbols(numeric "0" "1");
list-style-type: symbols(alphabetic "A" "B");
list-style-type: symbols(fixed "One" "Two");

The following is invalid because no symbols are supplied:

list-style-type: symbols(cyclic);

The following is invalid because the numeric system requires at least two symbols:

list-style-type: symbols(numeric "0");

The following is invalid because commas are not used to separate symbols:

list-style-type: symbols(cyclic "A", "B");

Accessibility

Use proper HTML list elements when presenting lists. Custom markers should supplement the list structure rather than replace it.

Decorative symbols should not be the only way important information is communicated.

For more complex or reusable counter styles, consider using the @counter-style rule.

Browser Support

The CSS symbols() function has Baseline Widely available browser support and works in modern versions of Chrome, Edge, Firefox, Safari, and other major browsers.

Support for individual symbol types and counter-related features may vary in older browser versions.

For current compatibility information, visit Can I Use? and search for symbols().

Specifications

The symbols() function is defined in the CSS Counter Styles Level 3 specification.

The specification defines anonymous counter styles, supported symbol systems, and the way symbols represent counter values.

Related CSS features include @counter-style, list-style-type, counter(), counters(), and the ::marker pseudo-element.