Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 122 ยท Lists

Lists

Learn how to build bulleted and numbered lists with ul, ol and li, how to choose the right one, and how to change bullets and numbers with list-style-type.

Lists are everywhere on the web: ingredients, steps in a tutorial, features of a product, search results, navigation menus. Whenever you have several related items in a row, a list is usually the right structure.

HTML has two everyday list types, unordered lists for items where the order doesn't matter and ordered lists for items where it does. Both are built from the same item element, <li>. This lesson shows how to write them, how to choose between them, and how to change the bullets and numbers with CSS.

Unordered lists: <ul>

An unordered list groups items whose order doesn't change their meaning. Browsers show them with bullets.

An unordered list

The structure is always the same:

  • <ul> (unordered list) wraps the whole list.
  • Each item is an <li> (list item).

You could pack your bag in any order; the list means the same thing. That is the test for an unordered list.

Ordered lists: <ol>

When the order matters, use <ol> (ordered list). The browser numbers the items for you:

An ordered list

Try moving the third item to the top. The numbers update automatically, because you never typed them. That is a big advantage over typing "1.", "2.", "3." into paragraphs: insert or remove a step and everything renumbers itself.

Ordered lists have a few more tricks, such as starting at a different number or counting backwards. They get their own lesson: Ordered List Options.

Which one should you use?

Ask yourself one question: would changing the order change the meaning?

Content Order matters? Use
Recipe steps Yes, you can't bake before mixing <ol>
Ingredients No <ul>
Top 10 movies of the year Yes, the rank is the point <ol>
Product features No <ul>
Breadcrumb trail Yes, it's a path <ol>
Site menu Usually no <ul>

Don't choose based on looks. If you want a numbered look for something unordered, or bullets on something ordered, you can change that with CSS while keeping the right element.

There is also a third type, the description list <dl>, for pairs of terms and descriptions such as a glossary. It works differently and is covered in Description Lists.

What can go inside a list

The rules are short but strict:

  • The only direct children of <ul> and <ol> are <li> elements (plus <script> and <template>, which display nothing).
  • An <li>, on the other hand, can contain almost anything: text, links, images, paragraphs, headings, even another list.
HTML
<!-- Wrong: text and a <p> directly inside <ul> -->
<ul>
  Our services:
  <p>Web design</p>
</ul>

<!-- Right: a heading outside the list, content inside <li> -->
<h3>Our services</h3>
<ul>
  <li>Web design</li>
  <li>
    <p><strong>Hosting</strong></p>
    <p>Fast servers in three regions, with daily backups.</p>
  </li>
</ul>

Putting a list inside a list item creates a nested list, the subject of Nested Lists.

Lists help screen-reader users. When a screen reader reaches a list, it announces something like "list, 4 items". People instantly know how long the list is and can skip it if it isn't relevant. Text that only looks like a list, with dashes or <br> tags, gets none of that.

Changing bullets and numbers with list-style-type

The markers come from CSS, so you can change them without touching the HTML. The list-style-type property accepts many values:

Value Marker
disc โ— filled circle (default for <ul>)
circle โ—‹ hollow circle
square โ–  filled square
decimal 1, 2, 3 (default for <ol>)
decimal-leading-zero 01, 02, 03
lower-alpha / upper-alpha a, b, c / A, B, C
lower-roman / upper-roman i, ii, iii / I, II, III
none no marker at all
"โ†’ " any string you choose
Marker styles

Two more tools from the example:

  • list-style-type: none removes the markers. Lists still keep their left padding, so add padding-left: 0 if you want them flush with the text. This is how navigation menus are usually built, as you saw in Building Navigation Menus.
  • The ::marker pseudo-element styles the bullet or number itself: its color, font size or weight, without affecting the item's text.

The shorthand. list-style combines the type, the position (inside or outside the text box) and an optional image in one property, for example list-style: square inside;. The default position, outside, keeps wrapped lines neatly aligned with the first line of text.

Avoid the old type attribute on <ul>. You may find code like <ul type="square">. That attribute is obsolete; use CSS instead. (The type attribute on <ol> is still valid, for a different reason that the next lesson explains.)

A Safari quirk with list-style: none

Safari's VoiceOver screen reader stops announcing a list as a list when its markers are removed with list-style: none. The reasoning is that a list without bullets may be used purely for layout. If the list really is a list, such as a menu or a set of cards, and you want it announced, add role="list" to the <ul> or <ol>:

HTML
<ul class="plain" role="list">
  <li>Home</li>
  <li>Blog</li>
</ul>

The role simply restores what the element already means. You will learn more about roles in ARIA.

Lists with rich items

Lists are not only for short lines of text. Because an <li> can contain almost anything, lists are the natural structure for any repeated group: search results, blog post previews, product cards, comments or links in a footer. If you can describe your content as "a set of things of the same kind", reach for a list.

A list of cards

Each card is a list item, so a screen reader announces "list, 3 items" before the first card. A sighted visitor can see at a glance that there are three trails; the list gives everyone else the same overview. CSS turns the bulleted list into a grid of cards, and the HTML stays simple.

Common mistakes

Most list bugs come from one of these habits:

  • Typing the markers yourself. Writing "1.", "โ€ข" or "-" at the start of paragraphs creates text that only looks like a list. It does not renumber itself, and software cannot tell it is a list.
  • Using <br> between items. A paragraph with line breaks is still one paragraph. Each item deserves its own <li>.
  • Using a list just to indent text. Lists add indentation by default, but if the content is not a list, use CSS padding or margin instead.
  • Choosing <ol> for the numbers' look. Pick the element by meaning; switch the markers with CSS.
  • Leaving out </li>. The browser usually copes, but explicit closing tags make your code easier to read and edit.
Real list versus fake list

To the eye, both look like lists. To the browser, only the second one has items. The console shows it: three items in the real list and zero in the fake one. Screen readers, search engines and your own CSS and JavaScript all see the page the way the console does.

Write items in parallel. Lists are easiest to read when every item has the same grammatical shape: all nouns ("Passport", "Charger"), or all instructions ("Grind the coffee", "Stir it in"). Keep punctuation consistent too: either every item ends with a period, or none does.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element fits a list of the ingredients for a salad?

    Ingredients can be listed in any order without changing the meaning, so an unordered list fits.
  2. 2. Which element can be a direct child of ul?

    Only <li> items (plus <script> and <template>) may sit directly inside <ul> and <ol>. Put other content inside an <li>.
  3. 3. You want letters (a, b, c) instead of numbers on a list of steps. What is the best approach?

    The steps are still ordered, so keep <ol> and change only the look with list-style-type: lower-alpha.
  4. 4. What does the ::marker pseudo-element let you style?

    ::marker targets the marker box only, so you can color the numbers without coloring the text.

Summary

  • <ul> is for items where the order doesn't matter; <ol> is for items where it does.
  • Every item is an <li>, and only <li> elements may be direct children of <ul> and <ol>.
  • Choose the element by meaning, then change the look with CSS.
  • list-style-type sets the marker: disc, square, decimal, lower-alpha, upper-roman, a custom string or none.
  • ::marker styles the marker itself.

Next lesson: Ordered List Options.