Native list attributes in HTML

Ordered lists occupy a place in the earliest history of HTML: among the first 18 tags that made up the language, list elements were already present, though how they rendered was left open — bullets for unordered lists, a run of numbered paragraphs for ordered ones. Demand soon pushed past that baseline, and a set of list attributes accumulated over the years to cover the gaps.

start

A list's starting point is set with start, which accepts an integer. The value carries no positivity requirement — zero and negative integers are legal too.

<ol start="2">
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

For instance, the default starting value of ol elements is 1.

<ol start="0">
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

<ol start="-2">
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

type

The type attribute selects the representation used for the counter, roughly the role of CSS's list-style-type, but with its own narrower set of applications; the two shouldn't be swapped interchangeably. Accepted values:

  • 1 — decimal numbers (the default)
  • a — lowercase alphabetic
  • A — uppercase alphabetic
  • i — lowercase Roman numerals
  • I — uppercase Roman numerals
<ol type="a">
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

<ol type="i">
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

Applying type to ol is odd enough already, though it retains some use cases. On ul the practice is straight-up deprecated.

value

Where start shifts a whole list, value targets one li and assigns its number; every li after it is renumbered from that point.

<ol>
  <li>Bread</li>
  <li value="4">Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

reversed

A boolean attribute that flips the counting direction, so items descend from the highest number to the lowest.

<ol reversed>
  <li>Bread</li>
  <li>Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

Mixing them

Nothing prevents combining the attributes on a single ordered list when the need arises.

<ol reversed start="2" type="i">
  <li>Bread</li>
  <li value="4">Milk</li>
  <li>Butter</li>
  <li>Apples</li>
</ol>

Are the attributes still needed alongside CSS?

Not a simple yes or no. The first CSS specification, which already carried list-style-type and related list properties, arrived before HTML 3.2 — the first HTML spec to include some of these attributes. So on paper, CSS list styling predates the HTML attributes.

The practical argument is resilience. Strip CSS from a static page and it may lose its looks, but it should stay readable. type, for example, keeps an ordered list's meaning intact without any stylesheet, which matters in legal and technical documents. And several attributes had no CSS equivalent for years afterward — reversed, start and value among them.

Styling counters with CSS

In most cases a couple of rules is all a styled list needs, yet even within that brevity there are different routes to the same result.

::marker versus ::before

The ::marker pseudo-element stands in for a list item's counter portion. Being a pseudo-element, it exposes content, so any string can replace the counter's representation:

li::marker {
  content: "💜 ";
}

Pseudo-element content also takes images, opening the way to fully custom markers:

li::marker {
  content: url("./logo.svg") " ";
}

By default only li gets a ::marker. Setting display: list-item grants one to any element, as a hover on the h4 rows in that example shows:

h4 {
  display: list-item;
}

h4::marker {
  content: "◦ ";
}

Each h4 then carries a ::marker ready to be replaced with any string.

List Title

::marker is an unusual case. Described in the CSS spec more than 20 years ago, it only reached somewhat reliable support in 2020 and remains incomplete in Safari. Worse, only font-related properties (font-size, color) are permitted on it — no margin, no background-color.

The workaround many authors adopted is ::before: kill the native marker with list-style-type: none and draw the counter through ::before instead. Plenty of CSS in the wild follows exactly that pattern.

li {
  /* removes ::marker */
  list-style-type: none;
}

li::before {
  /* mimics ::marker */
  content: "▸ ";
}

list-style-type

Where list-style-type aims, it substitutes the ::marker's string. Unlike ::marker it has been available forever and is the default choice for list styling. It accepts a lot of counter styles built into browsers; in practice a handful get used. For unordered lists:

  • disc
  • circle
  • square
ul {
  list-style-type: square;
}

ul {
  list-style-type: circle;
}

And for ordered lists:

  • decimal
  • decimal-leading-zero
  • lower-roman
  • upper-roman
  • lower-alpha
  • upper-alpha
ol {
  list-style-type: upper-roman;
}

ol {
  list-style-type: lower-alpha;
}

A full list of valid counter styles lives here. The property also takes none to drop the marker entirely, and since not long ago a <string> on ul elements as well.

ul {
  list-style-type: none;
}

ul {
  list-style-type: "➡️ ";
}
Two lists with two items each. The first list has no markers the second list has an emoji of a right arrow for the marker.

Building Counters Manually

Before custom counters, the only way to reverse a list or change its start was through the HTML reverse, start or value attributes — with no CSS equivalent. That meant editing the markup of every list individually instead of applying a single class. List attributes also couldn't control how numbering increments per item, made it awkward to attach a prefix or suffix, and most importantly never allowed numbering anything that wasn't a list. Custom counters remove all of those limits.

The workflow has four steps:

  1. Start the counter with the counter-reset property.
  2. Advance it with the counter-increment property.
  3. Assign values with the counter-set property.
  4. Render it using the counter() and counters() functions.

Because counters work on any collection of elements, a set of headings can be made to look like a list. That is a demonstration only: think about how assistive technologies such as screen readers will announce it, and see the accessibility section for the concerns involved.

<div class="index">
  <h2>The Old Buccaneer</h2>
  <h2>The Sea Cook</h2>
  <h2>My Shore Adventure</h2>
  <h2>The Log Cabin</h2>
  <h2>My Sea Adventure</h2>
  <h2>Captain Silver</h2>
</div>

Initiating and setting values

counter-reset takes a counter name (a custom ident) and an initial integer; omit the integer and it defaults to 0.

.index {
  counter-reset: index;
  /* The same as */
  counter-reset: index 0;
}

Several counters can be started in one space-separated declaration, each with its own value:

.index {
  counter-reset: index another-counter 2;
}

This starts index at the default 0 and another-counter at 2.

counter-set is similar, taking a name and an integer, but its value applies from that element onwards. Omitting the integer sets the counter to 0. Multiple counters can be set at once:

h2:nth-child(2) {
  counter-set: index;
  /* same as */
  counter-set: index 0;
}
h2:nth-child(3) {
  counter-set: index 5 another-counter 10;
}

The third h2 gets an index of 5 and another-counter of 10. If no active counter has that name, counter-set starts it at 0.

Incrementing

An initiated counter stays at 0 until elements increment it. counter-increment takes the counter name and an increment amount, defaulting to 1 when only the name is given. To have every h2 advance the counter by one:

h2 {
  counter-increment: index;
  /* same as */
  counter-increment: index 1;
}

Multiple counters can be incremented in a space-separated list:

h2 {
  counter-increment: index another-counter 2;
}

Here index advances by one and another-counter by two on each h2. If the named counter isn't active, counter-increment initiates it at 0.

Printing the result: counter()

Counting alone changes nothing on screen; the output functions do the displaying. counter() takes a counter name and returns its content as a string. When several active counters share a name, it picks the one defined nearest the element, so only one counter is output at a time.

Setting an element's display to list-item unlocks its ::marker pseudo-element:

h2 {
  display: list-item;
}

Writing counter() into the content property outputs the current count, and strings placed before or after the function add a prefix or suffix:

h2::marker {
  content: "Part " counter(index) ": ";
}
List of six chapters formatted as Part 1, Part 2, et cetera.

The ordinary ::before pseudo-element achieves the same thing:

h2::before {
  content: "Part " counter(index) ": ";
}

Joining nested counters: counters()

For nested lists, counter() forces you to declare a separate counter per nesting level and write matching output for each — workable only if the nesting depth is known in advance, which it often isn't.

counters() solves this. It also takes a counter name, but joins every active counter of that name into one string and prints it. Its second argument, a string such as "." or "-", is what separates the joined values.

Reset and increment a counter on each ol, letting each li advance its nearest counter by one:

ol {
  counter-reset: item;
}

li {
  counter-increment: item;
}

Then, instead of counter() (which would show only one counter per item), print them all together joined by a string like ".":

li::marker {
  content: counters(item, ".") ". ";
}
List of outdoor travel destinations containing nested lists formatted with decimal markers.

Counter styles and reversed numbering

Both output functions accept an optional last argument for the counter style — the same styles available to list-style-type. That lets the join example display Roman numerals and the earlier one alphabetic letters:

h2::marker {
  content: "Part " counter(index, upper-roman) ": ";
}
List of chapter titles with the marker saying Part 1, Part 2, et cetera, formatted as Roman numerals.
li::marker {
  content: counters(item, ".", lower-alpha) ". ";
}
List of outdoor travel destinations containing nested lists formatted with lowercase letters.

Counting backwards with custom counters requires knowing the element count in advance. To build a reversed Top Five list, initiate the counter at the total number of elements plus one (so it doesn't finish at 0):

<h1>Best rated animation movies</h1>

<ol>
  <li>Toy Story 2</li>
  <li>Toy Story 1</li>
  <li>Finding Nemo</li>
  <li>How to Train your Dragon</li>
  <li>Inside Out</li>
</ol>
ol {
  counter-reset: movies 6;
}

Then make the increment a negative integer:

li {
  counter-increment: movies -1;
}

Output it with counter() as usual:

li::marker {
  content: counter(movies) ". ";
}
List of five movies with the markers displayed in reverse order.

Firefox also supports the reversed() functional notation, which wraps the counter name at initiation to mark it as reversed — but it hasn't shipped in any other browser.

ol {
  counter-reset: reversed(movies);
}

li {
  counter-increment: movies;
}

li::marker {
  content: counter(movies) " .";
}

Building Custom Styles with @counter-style

Earlier techniques change where a counter starts and how fast it climbs, but the rendered output still relies on a built-in browser style, typically decimal. The @counter-style at-rule lets you define an entirely new style and reuse it anywhere a counter style is accepted, including list-style-type and the final argument of counter() and counters(). The rule takes a custom ident as its name:

@counter-style my-counter-style {
  /* etc. */
}

Writing the name in list-style-type or in a counter function then applies the style:

ul {
  list-style-type: my-counter-style;
}

li::marker {
  content: counter(my-counter, my-counter-style) ". ";
}

Descriptors go inside the rule. Only system is always required; symbols is required unless the system is additive or extends; everything else is optional.

  • system: the algorithm that builds each string representation. (Required)
  • negative: representation used for negative values.
  • prefix: a character placed before the marker and any minus sign.
  • suffix: a character placed after the marker and any minus sign.
  • range: the span in which the style applies; values beyond it fall through to fallback.
  • pad: a minimum width that shorter representations are padded out to.
  • fallback: the style used when a value can't be represented.
  • symbols: the characters consumed by the system algorithm.
  • additive-symbols: the symbols used when system is additive.
  • speak-as: how screen readers should announce the style.

The core descriptors

symbols (or additive-symbols) supply the characters; system decides what to do with them. Accepted values are cyclic, alphabetic, symbolic, additive, fixed and extends.

cyclic walks the symbols list and repeats it. A single character reproduces a plain bullet list:

@counter-style cyclic-example {
  system: cyclic;
  symbols: "⏵";
  suffix: " ";
}
  • bread
  • butter
  • milk
  • apples

Two or more characters alternate instead:

@counter-style cyclic-example {
  system: cyclic;
  symbols: "🔸" "🔹";
  suffix: " ";
}
List of four items, the first two items are prefixed with an orange diamond marker and a blue diamond marker, respectively.

fixed writes each symbol exactly once. With the pair above, only the first two items receive a custom marker; the rest drop to their fallback, decimal by default. Appending an <integer> to fixed shifts the starting item — the rule below begins counting at the fourth list item:

@counter-style multiple-example {
  system: fixed;
  symbols: "🔸" "🔹";
  suffix: " ";
}
List of four items, the first two items are prefixed with an orange diamond marker and a blue diamond marker, respectively.
Note:
@counter-style fixed-example {
  system: fixed 4;
  symbols: "💠";
  suffix: " ";
}
and
List of four items, the last item has a marker formatted as a snowflake emoji.
show the starting-integer variant, where fixed 4 maps item four to the first symbol.

numeric treats the symbols as a positional numeral system (base-2, base-8, base-16 and so on). Positional systems begin at 0, so the first symbol represents 0, the second 1, and so forth. That makes non-decimal ordered lists possible, such as hexadecimal:

@counter-style numeric-example {
  system: numeric;
  symbols: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "A" "B" "C" "D" "E" "F";
  suffix: ". ";
}
  1. bread
  2. butter
  3. milk
  4. apples

alphabetic works like a custom alphabetical system and resembles numeric, except there is no symbol for 0, so digits repeat once exhausted. With symbols of "A" "B" "C", the sequence runs "AA", "AB", "AC", then BA, BB, BC, and so on. Zero and negative values have no equivalent and fall back.

@counter-style alphabetic-example {
  system: alphabetic;
  symbols: "A" "B" "C";
  suffix: ". ";
}
  1. bread
  2. butter
  3. milk
  4. apples
  5. cinnamon

symbolic reuses the symbols, doubling, tripling and further repeating them each cycle: "A", "B", "C" become "AA", "BB", "CC", then "AAA", "BBB", "CCC". As with alphabetic, zero and negatives fall back.

@counter-style symbolic-example {
  system: symbolic;
  symbols: "A" "B" "C";
  suffix: ". ";
}
  1. bread
  2. butter
  3. milk
  4. apples
  5. cinnamon

additive assigns a numeric weight to each symbol and sums them, like making change with $5, $2 and $1 bills while using as few bills as possible — 10 becomes two $5s rather than ten $1s. Negative values fall back. This system uses additive-symbols instead of symbols:

@counter-style additive -example {
  system: additive;
  additive-symbols: 5 "5️⃣", 2 "2️⃣", 1 "1️⃣";
  suffix: " ";
}
List of five grocery items with the markers formatted as emoji numbers.

extends derives a new style from an existing one, taking a <counter-style-name> after the value. For instance, the closing parenthesis could replace the default decimal suffix:

@counter-style extends-example {
  system: extends decimal;
  suffix: ") ";
}
  1. bread
  2. butter
  3. milk
  4. cinnamon

The spec is explicit that an extends rule "must not contain a symbols or additive-symbols descriptor, or else the @counter-style rule is invalid."

Tuning presentation

negative overrides how negative values look. It accepts one or two characters: the first is prepended (the hyphen-minus "-" by default) and the second is appended. The rule below wraps negative representations in parentheses, producing (2), (1), 0, 1, 2:

@counter-style negative-example {
  system: extends decimal;
  negative: "(" ")";
}
  1. bread
  2. butter
  3. milk
  4. apples

prefix and suffix attach a character before and after the representation respectively; the example adds a leading character to every marker:

@counter-style prefix-suffix-example {
  system: extends decimal;
  prefix: "(";
  suffix: ") ";
}
  • bread
  • butter
  • milk
  • apples

range is an inclusive interval. Two integers, such as 2 4, bound the style to items 2, 3 and 4:

@counter-style range-example {
  system: cyclic;
  symbols: "‣";
  suffix: " ";
  range: 2 4;
}
  • bread
  • butter
  • milk
  • apples
  • cinnamon

infinite leaves one end open. Writing infinite 3 styles every item up to 3:

@counter-style range-example {
  system: alphabetic;
  symbols: "A" "B" "C";
  suffix: ". ";
  range: infinite 3;
}
  • bread
  • butter
  • milk
  • apples
  • cinnamon

pad pairs a minimum width <integer> with a padding character, which yields zero-padded counters:

@counter-style pad-example {
  system: extends decimal;
  pad: 3 "0";
}
  • bread
  • butter
  • milk
  • apples

fallback names the style to use when a count can't be represented. The fixed style below switches to lower-roman from the seventh item on:

@counter-style fallback-example {
  system: fixed;
  symbols: "⚀" "⚁" "⚂" "⚃";
  fallback: lower-roman;
}
  • bread
  • butter
  • milk
  • apples
  • cinnamon

speak-as advises speech readers:

  • auto — defer to the system default.
  • bullets — read as an unordered list; the default for cyclic.
  • numbers — read the numeric value in the content language; the default for additive, fixed, numeric and symbolic.
  • words — read the representation as words.
  • spell-out — read it letter by letter; the default for alphabetic.
  • <counter-style-name> — inherit that style's speak-as value.
@counter-style speak-as-example {
  system: extends decimal;
  prefix: "Item ";
  suffix: " is ";
  speak-as: words;
}

symbols()

The symbols() function creates a single-use counter style without declaring a full @counter-style, though it sacrifices some features. It works in list-style-type and inside counter() and counters(). Its browser support is appalling: only Firefox implements it.

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

Images as Markers

Four approaches are nominally available for image markers: the list-style-image property, the content property, the symbols descriptor in @counter-style, and the symbols() function. In practice only the first two are viable, since support for images in @counter-style and for symbols() generally isn't the best (it's pretty bad).

list-style-image and content

list-style-image accepts an image or a gradient; gradients can produce custom square bullets:

li {
  list-style-image: conic-gradient(red, yellow, lime, aqua, blue, magenta, red);
}
  • bread
  • butter
  • milk
  • apples

Changing the shape themselves would require further ::marker styling, which isn't currently possible. To use an image, pass its url() and keep it small enough to serve as a counter:

li {
  list-style-image: url("./logo.svg");
}
  • bread
  • milk
  • butter
  • apples

The content property behaves similarly: pass the image's url() and add left padding via an empty string.

li::marker {
  content: url("./logo.svg") " ";
}
A list with four grocery items. The marker is the CSS-Tricks logo.

Marker Spacing and the Limits of ::marker

Gaps between a marker and its list text are one of the hardest parts of list styling. Intuition says a larger margin on the marker or the list item should do the job, but neither padding nor margin is permitted on ::marker. A list actually has two elements — a wrapper (ol or ul) and the list item (li) — each carrying default padding and margin, so it isn't obvious which one to touch.

Šime Vidas' demo for the gap after the list marker makes the behavior testable: only the li's padding changes the spacing between ::marker and the text; every other spacing property shifts the whole list item. And even at padding: 0px a gap remains after ::marker, set by the browser and differing across browsers.

Positioning the Marker: list-style-position

By default, markers render outside the ul box. That produces familiar problems: markers escape their containers, text-align leaves them unaligned, and lists centered with flex or grid look off-center because the markers sit outside the box. The list-style-position property addresses this. It accepts outside (the default) or inside. Setting it to inside moves the ::marker into the box, at the cost of losing any spacing supplied by the list item's padding.

ul {
  border: solid 2px red;
}

.inside {
  list-style-position: inside;
}

.outside {
  list-style-position: outside;
}
  • bread
  • butter
  • milk
  • apple

Padding the Gap with content

As Vidas notes in the same article, appending a space to content feels more like a workaround than an optimal solution. Still, sticking purely with ::marker leaves no correct way to space the marker from the text — particularly for the many people who prefer list-style-position: inside. The simplest fix is to suffix the content property with an empty string.

li::marker {
    content: "•   ";
}
  • bread
  • milk
  • butter
  • apples

That approach only applies if you insist on the ::marker pseudo-element. In practice there is a better way to place the marker: not use it at all.

Switching to ::before

::marker cannot be laid out with CSS Grid or Flexbox, since setting li's display to anything other than list-item removes the marker, and its height and width can't be set for alignment. For simple styling it works fine; for anything more involved it falls short and the ::before pseudo-element takes over. With ::before, Flexbox becomes available and supplies two capabilities missing before: vertically centering the marker against the text, and easily widening the gap after the marker.

li {
  display: flex;
  align-items: center; /* Vertically center the marker */
  gap: 20px; /* Increases the gap */

  list-style-type: none;
}

The original ::marker is removed by changing the display.

Accessibility Trade-offs

Earlier sections turned non-list elements into things that look like lists, which raises the question of whether that hurts accessibility. It depends. For visual users every example renders fine, but some lack the markup assistive technology needs for navigation. In the initial demo, the listing titles are decoration because the heading structure already carries the markup, and the same holds for the counting-siblings demo, which assistive technology users can read through headings. Those are the exception, though. Several examples would fail if a list must be announced as a list by screen readers. This earlier list:

<div class="index">
  <h2>The Old Buccaneer</h2>
  <h2>The Sea Cook</h2>
  <h2>My Shore Adventure</h2>
  <h2>The Log Cabin</h2>
  <h2>My Sea Adventure</h2>
  <h2>Captain Silver</h2>
</div>

…should be written as a list instead:

<ul class="index">
  <li>The Old Buccaneer</li>
  <li>The Sea Cook</li>
  <li>My Shore Adventure</li>
  <li>The Log Cabin</li>
  <li>My Sea Adventure</li>
  <li>Captain Silver</li>
</ul>

Listing elements is rarely decorative, so as a rule of thumb, use lists in the markup even when CSS will restyle them.