Title: CSS Lists Module Level 3
Shortname: css-lists
Level: 3
Group: CSSWG
Status: ED
Work Status: Exploring
ED: https://drafts.csswg.org/css-lists-3/
TR: https://www.w3.org/TR/css-lists-3/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Former Editor: Ian Hickson, Google, ian@hixie.ch
Former Editor: Tantek Çelı̇k, Formerly of Microsoft, tantekc@microsoft.com
Previous Version: https://www.w3.org/TR/2014/WD-css-lists-3-20140320/
Previous Version: https://www.w3.org/TR/2011/WD-css3-lists-20110524/
!Contributors: Simon Montagu, AOL-TW/Netscape, smontagu@netscape.com
!Contributors: Daniel Yacob, yacob@geez.org
!Contributors: Christopher Hoess, choess@stwing.upenn.edu
!Contributors: Daniel Glazman, AOL-TW/Netscape, glazman@netscape.com
Abstract: 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.
Warning: not ready

spec:css-pseudo-4; type:selector; text:::before

Introduction

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

Declaring a List Item

Markers

The ''::marker'' Pseudo-Element

		            This is the first paragraph
		            in this document.

		  Note 1:   This is a very short
		            document.

		            This is the end.
		

		        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 ...
		

Generating The ''::marker'' Boxes

'list-style-image' is a valid image

The contents of the ''::marker'' are an anonymous inline replaced element representing the <>, followed by a text run containing a single space (U+0020 SPACE).

'list-style-type' is a <>

The contents of the ''::marker'' are a text run containing the <>.

'list-style-type' is a <>

The contents of the ''::marker'' are a text run containing the ''@counter-style/prefix'' of the <>, followed by the result of generating a counter representation for the <> and the value of the list-item counter on the originating element, followed by a text run containing the ''@counter-style/suffix'' of the <>.

otherwise

The ''::marker'' has no contents.

Image Markers: the 'list-style-image' property

	Name: list-style-image
	Value: <> | none
	Initial: none
	Applies to: list items
	Inherited: yes
	Percentages: n/a
	Media: visual
	Computed value: computed value of the <>, or ''list-style-image/none''
	

<>

Specifies that the ''::marker'' for the list item should show the specified <>. If the <> ends up being an invalid image, this value instead does nothing (like ''list-style-image/none'').

none

Does nothing. Instead, 'list-style-type' will be consulted to determine how to fill the ''::marker''.

li { list-style-image: url("http://www.example.com/ellipse.png") }

Text-based Markers: the 'list-style-type' property

	Name: list-style-type
	Value: <> | <> | none
	Initial: disc
	Applies to: list items
	Inherited: yes
	Percentages: n/a
	Media: visual
	Computed value: specified value
	

<>

The ''::marker''‘s contents will be generated according to the rules for that counter style. [[!CSS-COUNTER-STYLES-3]]

<>

The ''::marker'' will contain the <>.

none

The ''::marker'' will not contain anything.

			ul { list-style-type: "★"; }
			/* Sets the marker to a "star" character */

			p.note {
				display: list-item;
				list-style-type: "Note: ";
				list-style-position: inside;
			}
			/* Gives note paragraphs a marker consisting of the string "Note: " */

			ol { list-style-type: upper-roman; }
			/* Sets all ordered lists to use the upper-roman counter-style
			   (defined in the Counter Styles specification [[CSS-COUNTER-STYLES]]) */

			ul { list-style-type: symbols(repeating '○' '●'); }
			/* Sets all unordered list items to alternate between empty and
			   filled circles for their markers. */

			ul { list-style-type: none; }
			/* Suppresses the marker entirely, unless list-style-image is specified
			   with a valid image. */
		

Positioning Markers: The 'list-style-position' property

	Name: list-style-position
	Value: inside | outside
	Initial: outside
	Applies to: list items
	Inherited: yes
	Percentages: n/a
	Media: visual
	Computed value: specified value (but see prose)
	

inside

No special effect. (The ''::marker'' is an inline element at the start of the list item's contents.)

outside

The 'position' property on the marker computes to ''marker''. Additionally, the base directionality of the marker (used as an input to the bidi resolution algorithm) must be taken from the marker's marker positioning reference element. If the list item is inline, this value instead computes to ''inside''.

			<style>
				ul.compact { list-style: inside; }
				ul         { list-style: outside; }
			</style>
			<ul class=compact>
				<li>first "inside" list item comes first</li>
				<li>second "inside" list item comes first</li>
			</ul>
			<hr>
			<ul>
				<li>first "outside" list item comes first</li>
				<li>second "outside" list item comes first</li>
			</ul>
		

			  * first "inside" list
			  item comes first
			  * second "inside" list
			  item comes second

			========================

			* first "outside" list
			  item comes first
			* second "outside" list
			  item comes second

Styling Markers: the 'list-style' shorthand property

	Name: list-style
	Value: <<'list-style-type'>> || <<'list-style-position'>> || <<'list-style-image'>>
	Initial: see individual properties
	Applies to: list items
	Inherited: see individual properties
	Percentages: see individual properties
	Media: visual
	Computed value: see individual properties
	

			ul { list-style: upper-roman inside }  /* Any UL */
			ul ul { list-style: circle outside } /* Any UL child of a UL */
		

			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 */
		

			ol.alpha li { list-style: lower-alpha; }
			ul li       { list-style: disc; }
		

			ol.alpha > li { list-style: lower-alpha; }
			ul > li       { list-style: disc; }
		

			ol.alpha { list-style: lower-alpha; }
			ul       { list-style: disc; }
		

Marker Positioning

This section is not ready for implementation. It is an unreviewed rough draft that hasn't even been properly checked for Web-compatibility. Feel free to send feedback, but DON'T USE THIS PART OF THE SPEC.

The ''marker'' value for 'position'

	Name: position
	New values: marker
	Computed value: see prose, otherwise same as normal
	

ancestor list item

The ancestor list item is the marker's nearest list item ancestor element.

marker positioning reference element

If the ancestor list item has ''marker-side:list-item'', the marker positioning reference element is the ancestor list item. Otherwise, if the ancestor list item has ''marker-side:list-container'' and has a parent element, the marker positioning reference element is that parent. Otherwise, the marker positioning reference element is the ancestor list item.

list item positioning edge

The border edge of the ancestor list item corresponding to the "inline-start" edge of the marker positioning reference element.

marker positioning edge

The outer edge of the marker that's on the opposite side from the list item positioning edge. For example, if the list item positioning edge ended up being the left border edge of the ancestor list item, the marker positioning edge would be the right margin edge of the marker.

			<style>
			ol { list-style: none; }
			.marker { position: marker; }
			</style>
			<ol>
			  <li>
			    <span class='marker'>(a)</span> Definitions.— For purposes of this section—
			    <ol>
			      <li><span class='marker'>(1)</span> the term “agency” means agency as...
			      <li><span class='marker'>(2)</span> the term “individual” means a citizen...
			    </ol>
			  <li>
			    <span class='marker'>(b)</span> Conditions of Disclosure.— No agency shall disclose...
			    <ol>
			      <li><span class='marker'>(1)</span> to those officers and employees of the agency...
			      <li><span class='marker'>(2)</span> required under section 552 of this title;
			    </ol>
			</ol>
		

			(a) Definitions.— For purposes of this section—
			    (1) the term “agency” means agency as...
			    (2) the term “individual” means a citizen...
			(b) Conditions of Disclosure.— No agency shall disclose...
			    (1) to those officers and employees of the agency...
			    (2) required under section 552 of this title;
		

The 'marker-side' property

	Name: marker-side
	Value: list-item | list-container
	Initial: list-item
	Applies to: list items
	Inherited: yes
	Percentages: n/a
	Media: visual
	Computed value: specified value
	

list-item

Any associated markers base their positioning off of the directionality of the list item.

list-container

The associated markers instead base their positioning off of the directionality of the list item's parent element. The normative meaning of this is specified in the section defining position:marker.

			<ul>
			  <li>english one
			  <li dir=rtl>OWT WERBEH
			  <li>english three
			  <li dir=rtl>RUOF WERBEH
			</ul>
		

* english one
		 OWT WERBEH *
* english three
		RUOF WERBEH *

* english one
*    OWT WERBEH
* english three
*   RUOF WERBEH

Automatic Numbering With Counters

Manipulating Counters: the 'counter-increment', 'counter-set' and 'counter-reset' properties

	Name: counter-reset
	Value: [ <> <>? ]+ | none
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: n/a
	Media: all
	Computed value: specified value
	

none

This element does not create any new counters.

<> <>?

The element creates one or more new counters. Each <> names a new counter to be created. If an <> is provided after an <>, the starting value of the new counter is that integer. Otherwise, the starting value of the new counter is ''0''. Implementations may have implementation-specific limits on the maximum or minimum value of a counter. If an increment would push the counter's value beyond these limits, the increment must be ignored, and the counter's value remain unchanged.

	Name: counter-set
	Value: [ <> <>? ]+ | none
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: n/a
	Media: all
	Computed value: specified value
	

	Name: counter-increment
	Value: [ <> <>? ]+ | none
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: n/a
	Media: all
	Computed value: specified value
	

none

This element does not alter the value of any counters.

<> <>?

The element alters the value of one or more counters on it. If there is not currently a counter of the given name on the element, the element creates a new counter of the given name with a starting value of ''0'' (though it may then immediately set or increment that value to something different). If an <> is provided after an <>, it sets the innermost counter of the given name's value to that integer (for 'counter-set') or increments the value of the innermost counter of the given name by that integer (for 'counter-increment'). Otherwise, the innermost counter of the given name's value is set to ''0'' (for 'counter-set') or incremented by ''1'' (for 'counter-increment').

			h1::before {
					content: "Chapter " counter(chapter) ". ";
					counter-increment: chapter;  /* Add 1 to chapter */
					counter-reset: section;      /* Set section to 0 */
			}
			h2::before {
					content: counter(chapter) "." counter(section) " ";
					counter-increment: section;
			}
		

				h1 { counter-reset: section -1 }
				h1 { counter-reset: imagenum 99 }
			

H1 { counter-reset: section -1 imagenum 99 }

Creating and Inheriting Counters

			<ul style='counter-reset: example 0;'>
				<li id='foo' style='counter-increment: example;'>
					foo
					<div id='bar' style='counter-increment: example;'>bar</div>
				</li>
				<li id='baz'>
					baz
				</li>
			</ul>
		

• If no counters of that name exist on the element, create a new counter with that name on the element.
• Otherwise, if a counter of that name exists on the element, and it was created by a preceding sibling, replace the innermost counter of that name on the element with a newly-created counter with that name.
• Otherwise, create a new counter with that name and nest it inside of the innermost counter with that name.

Nested Counters

			ol { counter-reset: item }
			li { display: block }
			li::before { content: counter(item) ". "; counter-increment: item }
		

Counters in elements that do not generate boxes

			h2 { counter-increment: count2; }
			h2.secret { display: none; }
		

Outputting Counters: the ''counter()'' and ''counters()'' functions

		counter()  =  counter( <>, [ <> | none ]? )
		counters() = counters( <>, <>, [ <> | none ]? )
	

			H1::before        { content: counter(chno, upper-latin) ". " }
			/* Generates headings like "A. A History of Discontent" */

			H2::before        { content: counter(section, upper-roman) " - " }
			/* Generates headings like "II - The Discontent Part" */

			BLOCKQUOTE::after { content: " [" counter(bq, decimal) "]" }
			/* Generates blockquotes that end like "... [3]" */

			DIV.note::before  { content: counter(notecntr, disc) " " }
			/* Simply generates a bullet before every div.note */

			P::before         { content: counter(p, none) }
			/* inserts nothing */
		

			<ul>
				<li>one</li>
				<li>two
					<ul>
						<li>nested one</li>
						<li>nested two</li>
					</ul>
				</li>
				<li>three</li>
			</ul>
			<style>
			ul { counter-reset: list-item; }
			li { counter-increment: list-item; }
			li::marker { content: '(' counters(list-item,'.') ') '; }
			</style>
		

			(1) one
			(2) two
				 (2.1) nested one
				 (2.2) nested two
			(3) three
		

			<h1>First H1</h1>
			...
			<h2>First H2 in H1</h2>
			...
			<h2>Second H2 in H1</h2>
			...
			<h3>First H3 in H2</h3>
			...
			<h1>Second H1</h1>
			...
			<h2>First H2 in H1</h2>
			...
			<style>
			body { counter-reset: h1 h2 h3; }
			h1   { counter-increment: h1; counter-reset: h2 h3;}
			h2   { counter-increment: h2; counter-reset:    h3; }
			h3   { counter-increment: h3; }
			h1::before { content: counter(h1,upper-alpha) ' '; }
			h2::before { content: counter(h1,upper-alpha) '.'
														counter(h2,decimal) ' '; }
			h3::before { content: counter(h1,upper-alpha) '.'
			                      counter(h2,decimal) '.'
			                      counter(h3,lower-roman) ' '; }
			</style>
		

			A First H1
			...
			A.1 First H2 in H1
			...
			A.2 Second H2 in H1
			...
			A.2.i First H3 in H2
			...
			B Second H1
			...
			B.1 First H2 in H1
			...
		

		/* 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; }
		/* Alternately, if Values & Units Level 3 is supported, replace
			 the above three lines with: */
		ul { list-style-type: disc; }
		ul ul { list-style-type: cycle(disc, square, 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 calc(attr(start integer, 1) - 1);
		}

		/* The value attribute on li elements */
		li[value] {
			counter-set: list-item attr(value integer, 1);
			counter-increment: none; /* Turn off default increase */
		}

		/* Handling reversed lists */
		ol[reversed] {
			counter-reset: list-item calc(attr(start integer, **magic**) + 1);
			/* Where **magic** is the number of child <li> elements. */
		}
		ol[reversed] > li {
			counter-increment: list-item -1;
		}

		/* Box Model Rules */
		ol, ul {
			display: block;
			margin: 1em 0;
			marker-side: list-container;
		}

		ol:dir(ltr), ul:dir(ltr) {
			padding-left: 40px;
		}
		ol:dir(rtl), ul:dir(rtl) {
			padding-right: 40px;
		}

		ol ol, ol ul, ul ul, ul ol {
			margin-top: 0;
			margin-bottom: 0;
		}

		li {
			text-align: match-parent;
		}

		li::marker {
			display: inline;
			text-align: end;
			unicode-bidi: isolate;
			/* 'position' computes to "static" or "marker" depending on list-style-position */
		}