CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc. This draft contains the features of CSS level 3 relating to list styling. It includes and extends the functionality of CSS level 2 [[!CSS21]], which builds on CSS level 1 [[CSS1]]. The main extensions compared to level 2 are a pseudo-element representing the list marker, a new ''hanging'' value for 'list-style-position', and a method for authors to define their own list-styles.
The list model in this module differs in some important ways from the list model in CSS2, specifically in its handling of markers. Implementation experience suggested the CSS2 model overloaded the ::before and ::after pseudo-elements with too much behavior, while at the same time introducing new properties when existing properties were sufficient.
Most block-level elements in CSS generate one principal block box. In this module, we discuss two CSS mechanisms that cause an element to have an associated marker: one method associates one principal block box (for the element's content) with a separate marker box (for decoration such as a bullet, image, or number), and the other inserts a marker box into the principal box. Unlike :before and :after content, the marker box cannot affect the position of the principal box, whatever the positioning scheme.
For instance, the following example illustrates how markers may be used to add parentheses around each numbered list item. This HTML application and style sheet:
<!doctype html>
<html>
<head>
<title>Creating a list with markers</title>
<style>
li::marker { content: "(" counter(list-item, lower-roman) ")"; }
li { display: list-item; }
</style>
</head>
<body>
<ol>
<li>This is the first item.</li>
<li>This is the second item.</li>
<li>This is the third item.</li>
</ol>
</body>
</html>
should produce something like this:
(i) This is the first item. (ii) This is the second item. (iii) This is the third item.
With descendant selectors and child selectors, it's possible to specify different marker types depending on the depth of embedded lists.
A future release of this module will probably include ways to render tree lists.
To declare a list item, the 'display' property should be set to ''list-item''. This, in addition to generating a ''::marker'' pseudo-element and enabling the properties described below for that element, causes that element to increment the list item counter ''list-item''. (This does not affect the specified or computed values of the counter properties.)
The ''list-item'' counter is a real counter, and can be directly affected using the 'counter-increment' and ''counter-reset'' properties. It can also be used in the ''counter()'' and ''counters()'' functions.
The CSS3 box module may define other 'display' values which generate a list marker. These should also affect the ''list-item'' counter.
Note that this new model makes the ''marker'' display type redundant. That display type is therefore obsolete in the CSS3 Lists model.
| Name: | list-style-type |
|---|---|
| Value: | <string> | <counter-style> | inline | none |
| Initial: | disc |
| Applies To: | all elements with ''display: list-item'' |
| Inherited: | yes |
| Media: | visual |
| Computed Value: | specified value |
When the 'list-style-image' property is ''none'' or not a valid image, the 'list-style-type' property is instead used to construct the default contents of a list item's marker.
The ''::marker'' pseudoelement's default contents must be the value of the ''list-item'' counter, formatted according to the given counter style. Algorithms for formatting a value according to a counter style are given later in this spec.
This specification defines a method for authors to create their own counter styles which may be used here. Additionally, many useful counter styles are predefined in the sections on Predefined Counter Styles and Additional Predefined Counter Styles.
| Name: | list-style-image |
|---|---|
| Value: | <image> | none |
| Initial | none |
| Applies To: | all elements with ''display: list-item'' |
| Inherited: | yes |
| Media: | visual |
| Computed Value: | specified value |
This property sets the image that will be used as the list item marker. When the <image> resolves to a valid image, it is used as the default contents of ''::marker'' instead of the value specified by 'list-style-type'.
If the value ''none'' is provided, or the <image> doesn't resolve to a valid image, then the default contents are given by 'list-style-type' instead.
The following example sets the marker at the beginning of each list item to be the image "ellipse.png".
LI { list-style-image: url("http://www.example.com/ellipse.png") }
| Name: | list-style-position |
|---|---|
| Value: | inside | hanging | outside |
| Initial: | outside |
| Applies To: | all elements with ''display: list-item'' |
| Inherited: | yes |
| Media: | visual |
| Computed Value: | specified value |
This property specifies the position of the ''::marker'' pseudo-element's box in the list item. Values have the following meanings:
Inline markers have some special behavior wrt white-space collapsing at the beginning of the list-item. I need to figure this out and spec it. (Since I have hanging and outside markers be abspos, it doesn't apply to them.)
Are the positioning rules for ''hanging'' and ''outside'' good?
Note that a marker is only generated if the computed value of the 'content' property for the element's ''::marker'' pseudo-element is not ''none''.
For example:
<!doctype html>
<html>
<head>
<title>Comparison of inside/outside position</title>
<style>
ul { list-style: outside; }
ul.compact { list-style: inside; }
</style>
</head>
<body>
<ul>
<li>first list item comes first</li>
<li>second list item comes second</li>
</ul>
<ul class=compact>
<li>first list item comes first</li>
<li>second list item comes second</li>
</ul>
</body>
</html>
The above example may be formatted as:

In right-to-left text, the markers would have been on the right side of the box.
| Name: | list-style |
|---|---|
| Value: | <'list-style-type'> || <'list-style-position'> || <'list-style-image'> |
| Initial: | N/A (shorthand property) |
| Applies To: | all elements with ''display: list-item'' |
| Media: | visual |
| Computed Value; | N/A (shorthand property) |
The 'list-style' property is a shorthand notation for setting the three properties 'list-style-type', 'list-style-image', and 'list-style-position' at the same place in the style sheet.
For example:
UL { list-style: upper-roman inside } /* Any UL */
UL > UL { list-style: circle outside } /* Any UL child of a UL */
Using a value of ''none'' in the shorthand is potentially ambiguous, as ''none'' is a valid value for both 'list-style-image' and 'list-style-type'; to resolve this ambiguity, a value of ''none'' in the shorthand must be applied to whichever of the two properties aren't otherwise set by the shorthand.
list-style: none disc; /* Sets the image to ''none'' and the type to ''disc''. */ list-style: none url(bullet.png); /* Sets the image to ''url(bullet.png)'' and the type to ''none''. */ list-style: none; /* Sets both image and type to ''none''. */ list-style: none disc url(bullet.png); /* Syntax error */
Although authors may specify 'list-style' information directly on list item elements (e.g., LI in HTML), they should do so with care. The following rules look similar, but the first declares a descendant selector and the second a (more specific) child selector.
OL.alpha LI { list-style: lower-alpha } /* Any LI descendant of an OL */
OL.alpha > LI { list-style: lower-alpha } /* Any LI child of an OL */
Authors who use only the descendant selector may not achieve the results they expect. Consider the following rules:
<!doctype html>
<html>
<head>
<title>WARNING: Unexpected results due to cascade</title>
<style>
ol.alpha li { list-style: lower-alpha; }
ul li { list-style: disc; }
</style>
</head>
<body>
<ol class=alpha>
<li>level 1
<ul>
<li>level 2</li>
</ul>
</li>
</ol>
</body>
</html>
The desired rendering would have level 1 list items with 'lower-alpha' labels and level 2 items with 'disc' labels. However, the cascading order will cause the first style rule (which includes specific class information) to mask the second. The following rules solve the problem by employing a child selector instead:
OL.alpha > LI { list-style: lower-alpha }
UL LI { list-style: disc }
Another solution would be to specify 'list-style' information only on the list type elements:
OL.alpha { list-style: lower-alpha }
UL { list-style: disc }
Inheritance will transfer the 'list-style' values from OL and UL elements to LI elements. This is the recommended way to specify list style information.
Markers are created by setting an element's 'display' property to ''list-item''. The ''list-item'' display type is, in every other respect, identical to the ''block'' display type. The marker box is only created if the computed value of the 'content' property for the pseudo-element is not ''none''.
Just like other generated content, markers generate a box when they're created, which has margins, border, padding, and everything else a box normally has. Markers are placed at the beginning of their superior parent's content, immediately before a ''::before'' pseudo-element on the same superior parent. Marker boxes are inline-block by default, and so a value of ''auto'' for 'width' resolves to the width of the marker's content. The value of 'list-style-position' on the marker's superior parent can vary the marker's directionality and the initial value of its ''position'' property.
In the following example, the content is centered within a marker box of a fixed width. This document:
<!doctype html>
<html>
<head>
<title>Content alignment in the marker box</title>
<style>
LI::marker {
content: "(" counter(counter) ")";
width: 6em;
text-align: center;
}
LI {
display: list-item;
counter-increment: counter;
}
</style>
</head>
<body>
<ol>
<li>This is the first item.</li>
<li>This is the second item.</li>
<li>This is the third item.</li>
</ol>
</body>
</html>
should render something like this:
(1) This is the
first item.
(2) This is the
second item.
(3) This is the
third item.
The next example uses markers to number notes (paragraphs).
The following document:
<!doctype html>
<html>
<head>
<title>Markers to create numbered notes</title>
<style>
P { margin-left: 12 em; }
P.Note::marker {
content: url("note.gif") "Note " counter(note-counter) ":";
text-align: left;
width: 10em;
}
P.Note {
display: list-item;
counter-increment: note-counter;
}
</style>
</head>
<body>
<p>This is the first paragraph in this document.</p>
<p class="Note">This is a very short document.</p>
<p>This is the end.</p>
</body>
</html>
should render something like this:
This is the first paragraph
in this document.
Note 1: This is a very short
document.
This is the end.
The following example illustrates how markers may be offset from their element. This HTML application and style sheet:
<!doctype html>
<html>
<head>
<title>Marker example</title>
<style>
P { margin-left: 8em } /* Make space for counters */
LI::marker { margin: 0 3em 0 0; content: counter(list-item, lower-roman) "."; }
LI { display: list-item }
</style>
</head>
<body>
<p>This is a long preceding paragraph ...</p>
<ol>
<li>This is the first item.</li>
<li>This is the second item.</li>
<li>This is the third item.</li>
</ol>
<p>This is a long following paragraph ...</p>
</body>
</html>
should render something like this:
This is a long preceding
paragraph ...
i. This is the first item.
ii. This is the second item.
iii. This is the third item.
This is a long following
paragraph ...
(Note the use of the implicit counter increment.)
If a ''::marker'' pseudo-element has its 'content' property set to ''normal'', the computed value of the marker's 'content' property must be constructed according to the following algorithm:
Given the following style sheet:
li { display: list-item; list-style-type: decimal /* initial value */; }
li::marker { content: normal /* initial value */; }
And the following document fragment:
<li>List Item</li>
The computed value of the 'content' property on the ''::marker'' pseudo-element of the list item element is:
counter(list-item, decimal) "."
In some situations, such as legal proceedings or official minutes, the precise form that the list marker takes is a vital part of the content. It's not acceptable for the marker to change just because the UA is not rendering CSS, or some server error is temporarily preventing the CSS file from being loaded, as the precise marker name is used to officially refer to that segment. The only way to guarantee that the marker will be rendered correctly, regardless of whether CSS is applied, is to specify the marker outside of CSS, directly in the document's markup. However, the page author may still want to style the marker in many of the ways that are available to them when using ordinary CSS-generated markers. To accomodate this, a new value for the 'display' property is defined.
| Name: | display |
|---|---|
| New Value: | marker |
| Applies to: | Children elements of display:list-item elements |
The ''marker'' value for 'display' indicates that an element is a candidate for having its contents used as a list marker. If the element is a child of a list item with ''list-style-type:inline'', and none of the element's previous siblings are candidates, the textual content of the element (such as what would be returned by the .textContent property on the element in HTML) must be used as the default contents of the ::marker pseudoelement on the element's parent. Otherwise, this value must be treated identically to ''inline-block''.
While authors may define their own counter styles using the ''@counter-style'' rule defined in this spec, there are many counter styles that CSS already defined in previous levels, and many more that can be usefully predefined. Appendix A contains a required UA stylesheet which defines a large number of counter styles using the ''@counter-style'' rule. A few styles require special handling beyond what can be expressed in a stylesheet, though. Those counter styles are described in this section.
CSS 2.1 defined three single-glyph counter styles (''circle'', ''disc'', and ''square''), but didn't define precisely how to render them, instead opting to describe generally how they should look and leaving it up to the UA to decide how to render the markers.
Appendix A gives normative definitions for these styles, but UAs may instead default to rendering these styles using a browser-generated image matching the description below. This only describes the rendering of the default counter styles associated with these names - if an author or user creates their own counter style with one of these names (overriding the UA-default version), they must be honored as normal.
If the UA chooses to use an image for the default rendering of these counter styles, the image must be scalable and designed to attractively fill a box 1em wide and 1em tall.
Nearly all counter styles can be described using the small set of algorithms described by the 'type' descriptor. A small handful, though, require more complex handling which is too specialized to warrant crafting a generalized algorithm to use in 'type'. Instead, their algorithms are described here. Just like a counter style defined with the @counter-style rule, these counter styles can be overridden by creating another @counter-style rule with the same name, or can be used in the 'override' type to alter their descriptors while keeping the algorithms described here.
The Ethiopian numbering system is defined for all positive non-zero numbers. The following algorithm converts decimal digits to ethiopic numbers.
| Tens | Units | ||||
|---|---|---|---|---|---|
| Values | Codepoints | Values | Codepoints | ||
| 10 | ፲ | U+1372 | 1 | ፩ | U+1369 |
| 20 | ፳ | U+1373 | 2 | ፪ | U+136A |
| 30 | ፴ | U+1374 | 3 | ፫ | U+136B |
| 40 | ፵ | U+1375 | 4 | ፬ | U+136C |
| 50 | ፶ | U+1376 | 5 | ፭ | U+136D |
| 60 | ፷ | U+1377 | 6 | ፮ | U+136E |
| 70 | ፸ | U+1378 | 7 | ፯ | U+136F |
| 80 | ፹ | U+1379 | 8 | ፰ | U+1370 |
| 90 | ፺ | U+137A | 9 | ፱ | U+1371 |
For this system, the name is "ethiopian-numeric", the lower range bound descriptor is 1, the upper range bound descriptor is infinity, and the rest of the descriptors have their initial value.
Is there a better suffix to use than the initial (".")? The alphabetic ethiopic systems use a different suffix.
The decimal number 100, in ethiopic, is ፻ U+137B
The decimal number 78010092, in ethiopic, is ፸፰፻፩፼፻፺፪ U+1378 U+1370 U+137B U+1369 U+137C U+137B U+137A U+136A.
The decimal number 780000001092, in ethiopic, is ፸፰፻፩፼፻፼፻፺፪ U+1378 U+1370 U+137B U+1369 U+137C U+137B U+137C U+137B U+137A U+136A.
Chinese, Japanese, and Korean have longhand counter styles, which have a structure similar to "one hundred thirteen thousand and twenty-three" in English. Each has both formal and informal variants. The formal styles are typically used in financial and legal documents, as their characters are more difficult to alter.
The following counter styles are defined in this section:
Add an example to each of the above types.
The Japanese and Korean longhand counter styles are expressed using the ''additive'' counter algorithm, in the Additional Predefined Counter Styles section.
The Chinese longhand styles are defined over the range -9999 to 9999. For numbers outside this range, the ''cjk-decimal'' style is used. All of the styles are defined by almost identical algorithms (specified as a single algorithm here, with the differences called out when relevant), but use different sets of characters. The list following the algorithm gives the name of each counter style using this algorithm, and the individual character sets used by each style.
For all of these counter styles, the suffix descriptor is "、" U+3001, the fallback descriptor is ''cjk-decimal'', the lower range bound descriptor is -9999, and the upper range bound descriptor is 9999.
The following tables define the characters used in these styles:
| Values | Codepoints |
|---|---|
| Digit 0 | 零 U+96F6 |
| Digit 1 | 一 U+4E00 |
| Digit 2 | 二 U+4E8C |
| Digit 3 | 三 U+4E09 |
| Digit 4 | 四 U+56DB |
| Digit 5 | 五 U+4E94 |
| Digit 6 | 六 U+516D |
| Digit 7 | 七 U+4E03 |
| Digit 8 | 八 U+516B |
| Digit 9 | 九 U+4E5D |
| Tens Digit Marker | 十 U+5341 |
| Hundreds Digit Marker | 百 U+767E |
| Thousands Digit Marker | 千 U+5343 |
| Negative Sign | 负 U+8D1F |
| Values | Codepoints |
|---|---|
| Digit 0 | 零 U+96F6 |
| Digit 1 | 壹 U+58F9 |
| Digit 2 | 贰 U+8D30 |
| Digit 3 | 叁 U+53C1 |
| Digit 4 | 肆 U+8086 |
| Digit 5 | 伍 U+4F0D |
| Digit 6 | 陆 U+9646 |
| Digit 7 | 柒 U+67D2 |
| Digit 8 | 捌 U+634C |
| Digit 9 | 玖 U+7396 |
| Tens Digit Marker | 拾 U+62FE |
| Hundreds Digit Marker | 佰 U+4F70 |
| Thousands Digit Marker | 仟 U+4EDF |
| Negative Sign | 負 U+8D1F |
| Values | Codepoints | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Digit 0 | 零 U+96F6 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 1 | 一 U+4E00 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 2 | 二 U+4E8C | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 3 | 三 U+4E09 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 4 | 四 U+56DB | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 5 | 五 U+4E94 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 6 | 六 U+516D | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 7 | 七 U+4E03 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 8 | 八 U+516B | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Digit 9 | 九 U+4E5D | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tens Digit Marker | 十 U+5341 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Hundreds Digit Marker | 百 U+767E | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Thousands Digit Marker | 千 U+5343 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Negative Sign | 負 U+8CA0
Note: Chinese, Japanese, and Korean longhand numbering is actually defined up to 1072. In practice, lists are rarely, if ever, numbered above ten thousand, so these styles have been limited to their first "group". Defining Custom Counter Styles: the ''@counter-style'' ruleCSS 2.1 defined a handful of useful counter styles based on the styles that HTML traditionally allowed on ordered and unordered lists. This tiny set, though, is quite inadequate for modern web pages; displaying an ordered list with markers based on the latin alphabet while the content is Arabic seems quite incongruous! Unfortunately, the set of potentially useful list styles is too large to specify ahead of time - the world contains thousands of languages and hundreds of scripts, not to mention the near-infinite stylistic variations found on the web that go beyond mere languaged-based variation. The ''@counter-style'' rule allows CSS to address this in an open-ended manner, by allowing the author to define their own counter styles. These styles can then be used in the 'list-style-type' property or in the ''counter()'' and ''counters()'' functions, exactly like the predefined counter styles in CSS. A counter style defines how to construct the representation of a counter value. Counter styles are composed of:
The algorithm is usually specified implicitly by a combination of the ''type'', ''glyphs'', and ''additive-glyphs'' properties, but some counter styles instead have their algorithm explicitly defined. The general form of an ''@counter-style'' rule is:
@counter-style <counter-style-name> {
[ descriptor: value; ]+
}
Each @counter-style rule specifies a value for every counter-style descriptor, either implicitly or explicitly. Those not given explicit value in the rule take the initial value listed with each descriptor in this specification. These descriptors apply solely within the ontext of the @counter-style rule in which they are defined, and do not apply to document language elements. There is no notion of which elements the descriptors apply to or whether the values are inherited by child elements. When a given descriptor occurs multiple times in a given @counter-style rule, only the last specified value is used; all prior values for that descriptor are ignored. User agents which do not understand the @counter-style rule encounter the opening curly bracket and ignore forward until the closing curly bracket. This at-rule conforms with the forward-compatible parsing requirement of CSS; parsers may ignore these rules without error. Any descriptors that are not recognized or implemented by a given user agent must be ignored. @counter-style rules require a 'type' descriptor; if this is missing the @counter-style is invalid and must be ignored. The <counter-style-name> must be be a valid identifier and must not be "decimal", "default", "hanging", "inherit", "initial", "inline", "inside", "none", or "outside"; otherwise the @counter-style is invalid and must be ignored. Counter algorithms: the 'type' descriptor
The 'type' descriptor specifies which algorithm will be used to construct the counter's representation based on the counter value. For example, ''repeating'' type counter styles just cycle through their glyphs repeatedly, while ''numeric'' type counter styles interpret their glyphs as digits and build their representation accordingly. The types are defined as follows: repeatingIf the type is ''repeating'', the 'glyphs' descriptor must contain at least one counter glyph. This type is defined over all counter values. The ''repeating'' counter type cycles repeatedly through its provided glyphs, looping back to the beginning when it reaches the end of the list, similar to the default ''disc'' counter style. It can be used for simple bullets (just provide a single counter glyph), or for cycling through multiple bullets. The first counter glyph is used as the representation of the value 1, the second counter glyph (if it exists) is used as the representation of the value 2, etc. In general, if there are N counter glyphs and a representation is being constructed for the value I, the representation is the counter glyph at index (I mod N) of the list of counter glyphs (0-indexed). A "triangle bullet" counter style can be defined as:
@counter-style triangle {
type: repeating;
glyphs: '▶';
suffix: '';
}
It will then produce lists that look like: ▶ One ▶ Two ▶ Three numericIf the type is ''numeric'', the 'glyphs' descriptor must contain at least two counter glyphs. This type is defined over all counter values. The ''numeric'' counter type cycles interprets the list of counter glyphs as digits to a number system, similar to the default ''decimal'' counter style. The first counter glyph in the list is interpreted as the digit 0, the second as the digit 1, and so on. If there are N counter glyphs, the representation is a base N number using the counter glyphs as digits. To construct the representation, run the following algorithm. Let N be the length of the list of counter glyphs, I initially be the counter value, S initially be the empty string, negative be a boolean flag that is initially false, and glyph(n) be the nth counter glyph in the list of counter glyphs (0-indexed).
A "trinary" counter style can be defined as:
@counter-style trinary {
type: numeric;
glyphs: '0' '1' '2';
}
It will then produce lists that look like: 1. One 2. Two 10. Three 11. Four 12. Five 20. Six alphabeticIf the type is ''alphabetic'', the 'glyphs' descriptor must contain at least two counter glyphs. This type is defined only over positive counter values. The ''alphabetic'' counter type interprets the list of counter glyphs as digits to an alphabetic numbering system, similar to the default ''lower-alpha'' counter style. Alphabetic numbering systems are commonly used for lists, and also appear in many spreadsheet programs to number columns. The first counter glyph in the list is interpreted as the digit 1, the second as the digit 2, and so on. If there are N counter glyphs, the representation is a base N alphabetic number using the counter glyphs as digits. Alphabetic numbering systems do not contain a digit representing 0. To construct the representation, run the following algorithm. Let N be the length of the list of counter glyphs, I initially be the counter value, S initially be the empty string, and glyph(n) be the nth counter glyph in the list of counter glyphs (0-indexed). While I is not equal to 0:
Finally, return S. A counter style using go stones can be defined as:
@counter-style go {
type: alphabetic;
glyphs: url(white.svg) url(black.svg);
suffix: '';
}
It will then produce lists that look like: This example requires support for SVG images to display correctly. Alphabetic styles may also be used to simulate a fixed-width numeric style:
@counter-style fixed-decimal {
type: alphabetic;
glyphs: '0' '1' '2' '3' '4' '5' '6' '7' '8' '9';
}
ol {
list-style: fixed-decimal;
counter-reset: list-item 1111;
}
This will produce lists that look like: 0001. One 0002. Two 0003. Three 0004. Four 0005. Five 0006. Six Two-digit numbers start at value 11, three-digit numbers start at value 111, etc.. Should I instead explicitly provide a fixed-width numeric counter type? I'd like to see if this sort of numbering is used in the wild first. symbolicIf the type is ''symbolic'', the 'glyphs' descriptor must contain at least one counter glyph. This type is defined only over positive counter values. The ''symbolic'' counter type cycles repeatedly through its provided glyphs, doubling, tripling, etc. the glyphs on each successive pass through the list. It can be used for footnote-style markers, and is also sometimes used for alphabetic-style lists for a slightly different presentation than what the ''alphabetic'' type presents. To construct the representation, let N be the length of
the list of counter glyphs, I initially be the counter
value, S initially be the empty string, and An "unary" counter style can be defined as:
@counter-style unary {
type: symbolic;
glyphs: '|';
}
It will then produce lists that look like: |. One ||. Two |||. Three ||||. Five |||||. Six The ''symbolic'' type will produce representations with sizes that are linear in the magnitude of the counter value. This can potentially be abused to generate excessively large representations and consume undue amounts of the user's memory or even hang their browser. User agents must support representations at least 20 characters long, but they may choose to instead use the fallback style for representations that would be longer than 20 characters. non-repeatingIf the type is ''non-repeating'', the 'glyphs' descriptor must contain at least one counter glyph. This type is defined over counter values in a finite range, starting with the first glyph value and having a length equal to the length of the list of counter glyphs. The ''non-repeating'' counter type is for representing counter styles that only have a finite number of representations. For example, Unicode defines several limited-length runs of special characters meant for lists, such as circled digits. When this type is specified, it may optionally have an integer provided after it, which sets the first glyph value. If it is omitted, the first glyph value is 1. The first counter glyph is the representation for the first glyph value, and subsequent counter values are represented by subsequent counter glyphs. Once the list of counter glyphs is exhausted, further values cannot be represented by this type, and must instead be represented by the fallback counter style. A "box-corner" counter style can be defined as:
@counter-style box-corner {
type: non-repeating;
glyphs: '◰' '◳' '◲' '◱';
suffix: ':';
}
It will then produce lists that look like: ◰: One ◳: Two ◲: Three ◱: Four 5: Five 6: Six additiveIf the type is ''additive'', the 'additive-glyphs' descriptor must contain at least one additive tuple. This type is nominally defined over all positive counter values (see algorithm, below, for exact details) The ''additive'' counter type takes as many of the largest glyphs that it can, then as many of the next largest glyph, etc. until the sum of all the glyphs equals the counter value. It can be used to implement roman numerals, and additionally is used to represent the numbering system of several languages which use different characters for the digits in differnt positions. To construct the representation, run this algorithm. let I initially be the counter value, S initially be the empty string, and glyph list initially be the list of additive tuples. If I is initially 0, and there is an additive tuple with a weight of 0, append that tuple's counter glyph to S and return S. Otherwise, while I is greater than 0 and there are elements left in the glyph list:
If the loop ended because I is 0, return S. Otherwise, the given counter value cannot be represented by this counter style, and must instead be represented by the fallback counter style. A "dice" counter style can be defined as:
@counter-style dice {
type: additive;
additive-glyphs: 6 '⚅', 5 '⚄', 4 '⚃', 3 '⚂', 2 '⚁', 1 '⚀';
suffix: '';
}
It will then produce lists that look like: ⚀ One ⚁ Two ⚂ Three ... ⚅⚄ Eleven ⚅⚅ Twelve ⚅⚅⚀ Thirteen The ''additive'' type will produce representations with sizes that are linear in the magnitude of the counter value. This can potentially be abused to generate excessively large representations and consume undue amounts of the user's memory or even hang their browser. User agents must support representations at least 20 characters long, but they may choose to instead use the fallback style for representations that would be longer than 20 characters. overrideThe ''override'' type allows an author to use the representation-construction algorithm of another counter style, but alter other aspects, such as the negative sign or the suffix. If a counter style uses the ''override'' type, any unspecified descriptors are taken from the specified counter style, rather than taking their initial values. If a @counter-style uses the ''override'' type, it must not contain a 'glyphs' or 'additive-glyphs' descriptor; otherwise it is invalid and must be ignored. If the specified counter style name isn't the name of any currently-defined counter style, it must be treated as if it was overriding the ''decimal'' counter style. Formatting negative values: the 'negative' descriptor
The 'negative' descriptor defines how to alter the representation when the counter value is negative. Not all counter types can render negative numbers. The first string in the value is prepended to the representation when the counter value is negative. The second string, if specified, is appended to the representation when the counter value is negative. For example, specifying ''negative: "(" ")";'' will make negative values be wrapped in parentheses, which is sometimes used in financial contexts, like "(2) (1) 0 1 2 3...". Symbols before the marker: the 'prefix' descriptor
The 'prefix' descripter specifies a string that is prepended to the marker representation. Prefixes are only added by the algorithm for constructing the default contents of the ::marker pseudo-element; the prefix is not added automatically when the counter() or counters() functions are used. Prefixes are added to the representation after negative signs. Symbols after the marker: the 'suffix' descriptor
The 'suffix' descripter specifies a string that is appended to the marker representation. Suffixes are only added by the algorithm for constructing the default contents of the ::marker pseudo-element; the suffix is not added automatically when the counter() or counters() functions are used. Suffixes are added to the representation after negative signs. Limiting the counter scope: the 'range' descriptor
The 'range' descriptor defines the range over which the counter style is defined. If a counter style is used to represent a counter value outside of its range, the counter style instead drops down to its fallback counter style. The first value represents the lower bound of the range (with 'infinite' representing negative infinity), and the second value represents the upper bound of the range (with 'infinite' representing positive infinity). This is an inclusive range - it includes both the lower and upper bound numbers. If the lower bound is higher than the higher bound, the descriptor is invalid and must be ignored. Some counter style types have their own implicit ranges, specified above
in the individual descriptions for each type. The explicit range given
by the ‘ There's also an implicit range coming from implementation limits. Should we require UAs to support all values in a signed 2-byte int, or a signed 4-byte int? Defining fallback: the 'fallback' descriptor
The 'fallback' descriptor specifies a fallback counter style to be used when the current counter style can't create a representation for a given counter value. For example, if a counter style defined with a range of 1-10 is asked to represent a counter value of 11, the counter value's representation is instead constructed with the fallback counter style (or possibly the fallback style's fallback style, if the fallback style can't represent that value, etc.). If the value of the 'fallback' descriptor isn't the name of any currently-defined counter style, the used value of the 'fallback' descriptor is ''decimal'' instead. Similarly, while following fallbacks to find a counter style that can render the given counter value, if a loop in the specified fallbacks is detected, the ''decimal'' style must be used instead. Note that it is not necessarily an error to specify fallback loops. For example, if an author desires a counter style with significantly different representations for even and odd counter values, they may find it easiest to define one style that can only represent odd values and one that can only represent even values, and specify each as the fallback for the other one. Though the fallback graph is circular, at no point do you encounter a loop while following these fallbacks - every counter value is represented by one or the other counter style. Is it useful to allow this case? If it would be significantly easier for implementations to just detect and reject circular fallback graphs, that would probably be acceptable. Marker characters: the 'glyphs' and 'additive-glyphs' descriptors
The 'glyphs' and 'additive-glyphs' descriptors specify the characters used by the marker-construction algorithm specified by the 'type' descriptor. The 'glyphs' descriptor must be specified if the counter type is ''repeating'', ''numeric'', ''alphabetic'', ''symbolic'', or ''non-repeating'', and the 'additive-glyphs' descriptor must be specified if the counter type is ''additive''; otherwise, the @counter-style is invalid and must be ignored. Some counter styles specify that the 'glyphs' descriptor must have at least two entries. If the counter's style is such a type, and the 'glyphs' descriptor has only a single entry, the counter style is invalid and must be ignored. Each entry in the 'glyphs' descriptor's value defines a counter glyph, which is interpreted differently based on the counter style's type. Each entry in the 'additive-glyphs' descriptor's value defines an additive tuple, which consists of a counter glyph and a non-negative integer weight. Each weight must be a non-negative integer, and the additive tuples must be specified in order of descending weight; otherwise, the @counter-style is invalid and must be ignored. Counter glyphs may be strings or images, and the two types can be mixed in a single descriptor. Counter representations are constructed by concatenating counter glyphs together. Image counter glyphs are rendered as inline replaced elements. The default object size of an image counter glyph is a 1em by 1em square. Sample style sheet for HTMLThis section is informative, nor normative. HTML itself defines the actual default properties that apply to HTML lists.
/* Set up list items */
li {
display: list-item;
/* counter-increment: list-item; (implied by display: list-item) */
}
/* Set up ol and ul so that they reset the list-item counter */
ol, ul {
counter-reset: list-item;
}
/* Default list style types for ordered lists */
ol {
list-style-type: decimal;
}
/* Default list style types for unordered lists up to 3 deep */
ul { list-style-type: disc; }
ul ul { list-style-type: square; }
ul ul ul { list-style-type: circle; }
/* The type attribute on ol and ul elements */
ul[type="disc"] { list-style-type: disc; }
ul[type="circle"] { list-style-type: circle; }
ul[type="square"] { list-style-type: square; }
ol[type="1"] { list-style-type: decimal; }
ol[type="a"] { list-style-type: lower-alpha; }
ol[type="A"] { list-style-type: upper-alpha; }
ol[type="i"] { list-style-type: lower-roman; }
ol[type="I"] { list-style-type: upper-roman; }
/* The start attribute on ol elements */
ol[start] {
counter-reset: list-item attr(start, integer, 1);
counter-increment: list-item -1;
}
/* The value attribute on li elements */
li[value] {
counter-reset: list-item attr(value, integer, 1);
counter-increment: none;
}
/* Box Model Rules */
ol, ul {
display: block;
margin: 1em 0;
padding-left: 40px;
}
ol ol, ol ul, ul ul, ul ol {
margin-top: 0;
margin-bottom: 0;
}
li {
text-align: match-parent;
}
li::marker {
display: inline-block;
margin-right: 1em;
text-align: end;
/* 'position' implied by list-style-position */
}
Appendix A: Additional Predefined Counter StylesWhile this specification defines a mechanism to allow authors to define almost any counter style they would want, forcing authors to redefine common styles every time they are used would be unnecessarily onerous. To aid in this regard, this specification predefines a large set of counter styles. User agents must include the following stylesheet as a user-agent stylesheet, so authors can depend on these styles being present. As with any ''@counter-style'' rule, the counter style definitions given here can be overridden by the author if they desire to attach a different style to a counter style name defined in this stylesheet.
Per http://www.ethiopic.org/w3c/css/WD-css3-lists-20020220-comments.html#armenianlists, we should have upper-coptic, lower-coptic, and coptic-numeric styles. The Coptic script was split out in Unicode 4.1 to occupy the block from U+2C80 to U+2CFF. Which characters should I use for each? Per http://www.ethiopic.org/w3c/css/WD-css3-lists-20020220-comments.html#armenianlists, putting the circumflex above a digit in armenian numbering multiplies the digit by 1000. The draft currently states a 10,000 multiplier. Which is correct? (Having the multiplier be 1000 means that you can potentially write the thousands digit two ways, using either the set of thousands digits or the set of ones digits with a circumflex. The examples given in the note appear to use the former.) ProfilesThis module has two profiles: CSS Level 1 and Full. There is no CSS2 profile because this module is incompatible with the CSS2 list model. The CSS Level 1 module consists of 'list-style', 'list-style-position', 'list-style-image', and 'list-style-type' (but only the following values: 'disc', 'circle, square', 'decimal', 'lower-roman', 'upper-roman', 'lower-alpha', 'upper-alpha', 'none'). It does not include the ::marker pseudo element. The Full profile contains everything. AcknowledgmentsThe following people and documentation they wrote were very useful for defining the numbering systems: Alexander Savenkov, Aryeh Gregor, Frank Tang, Jonathan Rosenne, Karl Ove Hufthammer, Musheg Arakelyan, Nariné Renard Karapetyan, Randall Bart, Richard Ishida Simon Montagu Changes From CSS2As described in the introduction section, there are significant changes in this module when compared to CSS2.
ReferencesNormative referencesOther referencesProperty indexIndex |