Lists are the structure of most information on the web. There are menus, steps, features, search results, and definitions.
HTML gives you three kinds, and choosing the right one depends on what the items are, not on how you want them to look.
The previous lesson in this module covered "How Do You Add Images, Figures and Captions Correctly?", and the next lesson in this module is about "How Do You Build an Accessible HTML Table?".
What are the three types?
There is an unordered list for items with no inherent order, there is an ordered list for items where the order carries the meaning, and there is a definition list for terms and their descriptions.
<!-- unordered: a set of things, order does not matter -->
<ul>
<li>Semantic HTML</li>
<li>Accessible forms</li>
<li>Responsive layout</li>
</ul>
<!-- ordered: the sequence is the information -->
<ol>
<li>Install the toolkit</li>
<li>Start the server</li>
<li>Open the page</li>
</ol>The difference is not the bullet or the number. That is entirely a styling decision. The difference is what the list means.
A screen reader that announces "list of three items" against "list of three items, 1 of 3" tells the user something different, and the second one is only true if the order matters.
When does the order matter?
You use an ordered list when a reader would notice if the items were rearranged. That is the installation steps, a procedure, a ranking, or a sequence of events.
You use an unordered list for a set of peers. That is the features, the links, the tags, or the ingredients.
<ol>
<li>Back up your data</li>
<li>Upgrade the service</li>
<li>Verify the data</li>
</ol>
<ul>
<li>Backups</li>
<li>Monitoring</li>
<li>Alerting</li>
</ul>The steps in a numbered list can be linked to directly, with the <li id="step-2"> plus the <a href="#step-2">. That is how a table of contents for a procedure is usually built.
How do the nested lists work?
A list can contain another list, and the nesting expresses the hierarchy. The second list goes inside the list item that it belongs to, and not directly inside the outer list.
<ul>
<li>Layout
<ul>
<li>Flexbox</li>
<li>Grid</li>
</ul>
</li>
<li>Scripting
<ul>
<li>DOM</li>
</ul>
</li>
</ul>The indentation of the source is only for readability. The browser nests correctly because of the tags.
But there is a rule worth keeping. You keep the nesting shallow, at three levels at most. Beyond that, a list of lists becomes hard to read and harder to use with a screen reader.
What is a definition list?
A definition list pairs terms with descriptions.
It is underused, and it is the right element whenever you are presenting a glossary, a specification, or a list of key-value facts.
<dl>
<dt>Server</dt>
<dd>The process that responds to requests for resources.</dd>
<dt>Client</dt>
<dd>The program that sends those requests, usually a browser.</dd>
</dl>The <dt> holds the term, and the <dd> holds its description. The two of them are associated programmatically, which is what a screen reader needs in order to read them as a pair and not as an undifferentiated blob of text.
How do you style a list without breaking it?
There are two habits that separate a well-styled list from a broken one.
First, you remove the markers and not the list itself. The list-style: none setting keeps the semantics, while removing the list element and using bare <div> elements throws them away.
Second, if you want the items horizontal, you keep the list vertical in the markup and you rotate the layout in the CSS, so the reading order still matches what the user sees.
/* keep the semantics, drop the marker */
.clean-list {
list-style: none;
margin: 0;
padding: 0;
}
/* a horizontal row of links that is still a list in the markup */
.nav-list {
display: flex;
gap: 1rem;
list-style: none;
margin: 0;
padding: 0;
}When a list is used purely for the layout, such as a set of boxes arranged in a row, then the honest choice is usually a different element.
A navigation bar is a list because it is a list of destinations. A row of cards is a row of cards, and a <div> or a <section> says that more clearly.
Can an ordered list start at a different number?
It can, and the attribute is the start.
It is worth knowing, because a list that continues from a previous section would otherwise restart at one, and it would confuse the reader.
<ol start="4">
<li>Fourth step</li>
<li>Fifth step</li>
</ol>
<ol reversed>
<li>Last thing to do</li>
<li>Second to last</li>
</ol>
<ol type="A">
<li>First option</li>
<li>Second option</li>
</ol>Setting the type="A" changes the marker to letters, and the reversed attribute counts down.
Both of them are presentational conveniences, so the usual advice applies. If the numbering carries a meaning that a sighted reader would miss, then you spell it out in the text instead.
A list that counts down while the steps are actually performed in the written order is a trap.
How do you control the markers and the numbers?
The default bullets, numbers, and letters are only the starting point.
The list-style family of properties gives you three separate controls.
The list-style-type chooses the marker. There is the disc, the circle, the square, the decimal, the lower-alpha, the upper-roman, and the none.
The list-style-position decides whether the marker sits outside the text box or inside it.
The list-style-image replaces the marker with your own image.
<ol class="steps">
<li>Write the draft</li>
<li>Get a second reader</li>
<li>Publish</li>
</ol>.steps {
list-style-type: upper-roman;
list-style-position: inside;
padding-inline-start: 0;
}
.steps li {
margin-block-end: 0.5rem;
color: #33475b;
}The list-style-type: none setting is the usual first step when you want to build custom navigation, and it is the reason so many stylesheets also set the padding-inline-start: 0. The default indentation of a list would otherwise leave a gap on the left.
There is one subtlety worth knowing. The marker itself is not an element, so most of your normal rules do not apply to it.
The exception is the ::marker pseudo-element, which lets you change the colour, the size, and the content of the bullet, but nothing else.
If you need a genuinely different marker, such as a number that is followed by a dot, then you either use the ::marker with a content value, or you drop the list entirely and you build the layout from ordinary elements.
Quick reference
- The
<ul>is for peers, the<ol>is when the order is the information, and the<dl>is for terms and definitions. - The bullets and the numbers are style and not meaning. The element carries the meaning.
- The nested lists go inside the list item, and three levels is the practical limit.
- You use the
list-style: noneto drop the markers without losing the semantics. - A navigation bar is genuinely a list, while a row of cards usually is not.
Try it yourself: you write an ordered list of five steps, and then you rewrite it as an unordered list, and you describe what a screen reader user would notice. Then you turn the ordered list into a horizontal navigation row by using flexbox, while keeping the list element, and you check that the reading order still makes sense.