CSS Lists Module Level 3

Editor’s Draft,

Specification Metadata
This version:
Latest published version:
Previous Versions:
Issue Tracking:
Inline In Spec
GitHub Issues
Tab Atkins (Google)
Former Editors:
(Formerly of Microsoft)
Suggest an Edit for this Spec:
GitHub Editor
Simon Montagu, AOL-TW/Netscape, smontagu@netscape.com
Daniel Yacob, yacob@geez.org
Christopher Hoess, choess@stwing.upenn.edu
Daniel Glazman, AOL-TW/Netscape, glazman@netscape.com


This draft contains the features of CSS level 3 relating to list styling. It includes and extends the functionality of CSS level 2 [CSS21]. The main extensions compared to level 2 are a pseudo-element representing the list marker, and some new ways to position markers.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-lists” in the title, preferably like this: “[css-lists] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

This specification defines the ::marker pseudo-element, the list-item display type that generates markers, and several properties controlling the placement and styling of markers.

It also defines counters, which are special numerical objects often used to generate the default contents of markers.

For instance, the following example illustrates how markers can be used to add parentheses around each numbered list item:
li::marker { content: "(" counter(list-item, lower-roman) ")"; }
li { display: list-item; }
  <li>This is the first item.
  <li>This is the second item.
  <li>This is the third item.

It should produce something like this:

  (i) This is the first item.
 (ii) This is the second item.
(iii) This is the third item.

Note: Note that this example is far more verbose than is usually needed in HTML, as the UA default style sheet takes care of most of the necessary styling.

With descendant selectors and child selectors, it’s possible to specify different marker types depending on the depth of embedded lists.

2. Declaring a List Item

A list item is any element with its display property set to list-item. List items generate ::marker pseudo-elements; no other elements do. Additionally, list items automatically increment an implied list-item counter (see §4.2 The Implicit list-item Counter).

3. Markers

The defining feature of the list item display type is its marker, a symbol or ordinal that helps denote the beginning of each list item in a list. In the CSS layout model, list item markers are represented by a marker box associated with each list item. The contents of this marker can be controlled with the list-style-type and list-style-image properties on the list item and