Going from the most basic ways to style lists directly in HTML to advanced customization techniques that are even capable of making things that aren't lists look like lists.
JD
Juan Diego RodríguezCSS-Tricks
·March 17, 2025·Guides
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.
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:
Not a simple yes or no. The first CSS specification, which already carried list-style-type and related list properties, arrived beforeHTML 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:
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.
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: "➡️ ";
}
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:
Start the counter with the counter-reset property.
Advance it with the counter-increment property.
Assign values with the counter-set property.
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.
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:
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, ".") ". ";
}
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:
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) ". ";
}
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:
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:
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:
and 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:
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.
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.
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:
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:
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:
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:
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") " ";
}
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.
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:
Imagine a CSS karaoke machine that displays a ball bouncing on text that incrementally highlights, based on progress through via speech recognition and running that kind of animation as a single predictable, holistic effect driven by one progress value. Staggering Scroll-Driven Animations with animation-range-start originally handwritten and published with love on CSS-Tricks . You should really ge
A big ol' roundup of Black Friday deals on front-end courses from the best independent publishers and educators in the business. 10 Big Ol’ 2027 Black Friday Deals originally handwritten and published with love on CSS-Tricks . You should really get the newsletter as well.