Symbols() - Function CSS

symbols()

Summary of characteristics of the symbols() function

Quick description
Defines the symbols used for custom numbering, as well as the type of numbering (numeric, alphabetical, and so on).
Status
Standard
Percentages
Not applicable.
W3C Module
CSS Counter Styles
References (W3C)
Document status: CR (Candidate Recommendation)

Syntax diagram of symbols().

symbols() - Syntax DiagramSyntax diagram of the symbols() CSS function. cyclic cyclic numeric numeric alphabetic alphabetic symbolic symbolic fixed fixed 'char' 'char' url('url') url('url')symbols()symbols()
Syntax diagram of the symbols() function.
The links in the diagram provide access to more details.

On the diagram, the terms in bold are the predefined words of CSS, the other terms are described below:

  • char is a string, but most often a single character.
  • url is a URL to an image file.

Description of the symbols() function.

The symbols() function defines a numbering, which can be used, for example, with a list-style-type property to number a series of li tags. It also defines the type of numbering: classic numeric, alphabetical, etc.

The @counter-style at-rule also allows you to define a numbering while offering even more configuration possibilities. In particular, the numbering defined by @counter-style is named and can therefore be re-used in several places.

Principle.

All numbering is built from symbols that can be characters or images. For example, classic numbering uses the numbers as symbols: 0,1,2,3,4,5,6,7,8,9.
The number of symbols can be any but there must generally be at least two.

It is then necessary to define how the numbering continues when the last symbol is reached. Several possibilities are proposed. Refer to the syntaxes described below.

⚠
Note: Few browsers currently process the symbols() function. The examples below are simulations, so they can be read on all browsers.

The symbols() value can be used with the following properties:

  • @counter-style : Creation of a custom counter that can be used in numbered lists.
  • list-style : Summary of the characteristics of bulleted or numbered lists.
  • list-style-type : Defines the type of bullets or numbering.

Syntaxes of the symbols() function.

  • list-style-type: symbols(numeric '⓵' '⓶' '⓷' ...); t c1 c2 c3

    The syntax of symbols() consists of a first parameter indicating the type of numbering, followed by a series of symbols. All these parameters are separated by spaces.

    1. t indicates the type of numbering, to be chosen from the values numeric, alphabetic, cyclic, fixed, symbolic. If no numbering type is specified, it will be set to symbolic by default.
    2. The values c1, c2 etc. are the symbols to be used for numbering. In principle, they are unique characters, but short texts can be considered.
      These are often special characters that are not on keyboards, we will use their hexadecimal code with the syntax:
      'a9' for the character © or
      'ca' for the character Ê.

    Another solution is to copy-paste the character itself into the CSS code. Refer to the UTF character codes page to find the codes and copy the characters.

  • list-style-type: symbols(symbolic '⭕' '🔴' '🔵' ...);

    The symbolic numbering type goes through all the symbols provided, with the first symbol corresponding to the number 1, the second symbol to the number 2, and so on. When the list of symbols has been fully explored, we start again by doubling the symbols, then tripling them, etc.
    If only one symbol is specified (which is quite rare), the number of symbols displayed will correspond to the number of the element.

    The first sample below is a simulation, as many browsers do not yet properly handle the symbols() function. The second sample should be displayed identically if your browser is compatible.

    ⭕
    One
    🔴
    Two
    🔵
    Three
    ⭕⭕
    Four
    🔴🔴
    Five
    🔵🔵
    Six
    ⭕⭕⭕
    Seven
    Simulation

    • One

    • Two

    • Three

    • Four

    • Five

    • Six

    • Seven
    Real numbering
  • list-style-type: symbols(numeric '⭕' '🔴' '🔵' ...);

    The numeric numbering type is the most classic. The first symbol is considered zero. The numbering therefore begins with the second symbol (considered 1). When the last symbol is reached, we continue with two symbols. This type of numbering is commonly used with numbers. At least two symbols must be specified.

    The first sample below is a simulation. The second sample should be displayed identically if the browser you are using is compatible.

    🔴
    One
    🔵
    Two
    🔴⭕
    Three
    🔴🔴
    Four
    🔴🔵
    Five
    🔵⭕
    Six
    🔵🔴
    Seven
    Simulation

    • One

    • Two

    • Three

    • Four

    • Five

    • Six

    • Seven
    Real numbering
  • list-style-type: symbols(alphabetic '⭕' '🔴' '🔵' ...);

    As the name suggests, the alphabetic numbering type is often used with letters. None of the symbols have the value zero. The numbering starts with the first symbol, then continues with the second symbol, and so on. When the last symbol is reached, we continue by juxtaposing two symbols. Etc.
    At least two symbols must be specified.

    If your browser correctly handles the symbols() function, the so-called "real" numbering below should be identical to the simulation.

    ⭕
    One
    🔴
    Two
    🔵
    Three
    ⭕⭕
    Four
    ⭕🔴
    Five
    ⭕🔵
    Six
    🔴⭕
    Seven
    Simulation
     

    • One

    • Two

    • Three

    • Four

    • Five

    • Six

    • Seven
    Real numbering
  • list-style-type: symbols(cyclic '⭕' '🔴' '🔵' ...);

    Cyclic numbering first explores all the symbols provided, and then, when the last symbol is reached, it starts again identically from the first symbol. In this type of numbering, it is possible to specify only one symbol, which will be used each time (This is the same as defining a bullet).

    If your browser correctly handles the symbols() function, the so-called "real" numbering below should be identical to the simulation.

    ⭕
    One
    🔴
    Two
    🔵
    Three
    ⭕
    Four
    🔴
    Five
    🔵
    Six
    ⭕
    Seven
    Simulation
     

    • One

    • Two

    • Three

    • Four

    • Five

    • Six

    • Seven
    Real numbering
  • list-style-type: symbols(fixed '⭕' '🔴' '🔵' ...);

    Fixed numbering explores all the symbols provided, and when the last symbol is reached, the numbering continues in classic numeric. There is no minimum or maximum limit on the number of symbols, but in principle at least as many as there are elements to be numbered.

    If your browser correctly handles the symbols() function, the so-called "real" numbering below should be identical to the simulation.

    ⭕
    One
    🔴
    Two
    🔵
    Three
    4
    Four
    5
    Five
    6
    Six
    7
    Seven
    Simulation
     

    • One

    • Two

    • Three

    • Four

    • Five

    • Six

    • Seven
    Real numbering
  • list-style-type: symbols(decimal url(...) url(...) url(...)...); ⚠ t i1 i2 i3

    The values i1, i2, etc. are images that will be used in place of symbols. This feature does not seem to be supported by any browser at the moment.

Examples with symbols() function.

Here are some examples of custom numbering.

  • January
  • February
  • March
  • April
  • May
  • June
  • July
  • August
  • September
  • October
  • November
  • December
  • January
  • February
  • March
  • April
  • May
  • June
  • July
  • August
  • September
  • October
  • November
  • December
  • January
  • February
  • March
  • April
  • May
  • June
  • July
  • August
  • September
  • October
  • November
  • December
Binary numbering

Simulator.

list-style-type :

Browsers compatibility with symbols() function.

Encore peu de navigateurs traitent correctement la fonction symbols(). A distinction must be made between the symbols() function used with the list-style-type or list-style property and the descriptor symbols used with the @counter-style directive.

Column 1
Support for the symbols() function with the list-style-type property or the list-style summary property, to generate custom numbering.
Column 2
Support for the symbols() function used with the @counter-style at rule.

Notes:

(2) Does not accept an image as a value for symbols.

1
symbols()
function
used with
list-style-type
2
symbols()
descriptor
used with
@counter-style
Estimated overall support.
2%
14%

Browsers on computers :

Mobile browsers :

Outdated or marginal browsers :

Internet Explorer

Baidu Browser

QQ Browser

Opéra Mobile

2

Firefox

2

Chrome

2

Safari

Edge

2

Opéra

2

Chrome pour Androïd

2

Safari sur IOS

Samsung Internet

2

UC Browser pour Androïd

Androïd Brower

2

Firefox pour Androïd

2

KaiOS Browser

Opéra mini

See Caniuse.com for more compatibility information.
Caniuse
Caniuse

Historic of the symbols() function.

  • CSS Counter Styles Level 3

    Introduced the symbols() function in conjunction with the list-style-type property.
    WD
    October 09, 2012
    Working Draft.
    CR
    February 03, 2015
    Candidate Recommendation.
    PR
    REC

See also, about custom numbering.

The symbols() function is described in the specification CSS Counter Styles.
These other definitions are also presented in this same module.

At-rules:

@counter-style
Langue française
Creation of a custom counter that can be used in numbered lists.

Descriptors :

additive-symbols
Langue française
A @counter-style descriptor, which defines the value of each of the symbols in a custom numbering.
fallback
Langue française
When used with @counter-style, sets an override numbering when the counter goes outside the boundaries of a custom numbering.
negative
Langue française
Descriptor usable with the @counter-style at-rule. Defines the symbol to be used for negative numbers (custom numbering).
prefix
Langue française
A descriptor that can be used with the @counter-style at-rule to define the character(s) to be added before the number, as part of a custom numbering.
range
Langue française
A descriptor that can be used with the @counter-style directive to define the validity range of a custom numbering.
suffix
Langue française
Descriptor usable with @counter-style. Defines the characters to be added after the number, in a custom numbering.
symbols
Langue française
A descriptor that can be used with the @counter-style at-rule. It lists the symbols to be used in custom numbering. Not to be confused with the function of the same name.