HTML Lists

Lists are everywhere on the web: shopping lists, recipe steps, navigation menus, product features, exam rules. HTML has three kinds of list, and choosing the right one tells the browser, and screen reader users, how the items relate to each other.

In this lesson you will learn unordered, ordered and description lists, how to put one list inside another, and how to control the numbering.

Unordered lists

Use an unordered list, <ul>, when the order of the items does not matter. Each item goes in an <li> (list item) element. Browsers show a bullet before each item.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unordered list</title>
</head>
<body>
  <h2>Pack for the Jaipur school trip</h2>
  <ul>
    <li>Water bottle</li>
    <li>Cap and sunscreen</li>
    <li>School ID card</li>
    <li>₹300 pocket money</li>
  </ul>
</body>
</html>

You could swap any two items and the list would mean the same thing. That is the test for <ul>.

Ordered lists

Use an ordered list, <ol>, when the order matters: steps in a process, a ranking, or directions. Browsers number the items automatically, so you never type the numbers yourself.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Ordered list</title>
</head>
<body>
  <h2>How to make masala chai</h2>
  <ol>
    <li>Boil one cup of water with crushed ginger and cardamom.</li>
    <li>Add one teaspoon of tea leaves and boil for a minute.</li>
    <li>Add half a cup of milk and sugar to taste.</li>
    <li>Bring it to the boil again, then strain into cups.</li>
  </ol>
</body>
</html>

If you add a new step in the middle, the browser renumbers everything for you. That alone is a good reason to let HTML do the counting.

Controlling the numbers

Three attributes change how an ordered list counts:

<h2>Top 3 run scorers of the school tournament</h2>
<ol reversed>
  <li>Kabir, 212 runs</li>
  <li>Aarav, 240 runs</li>
  <li>Rohan, 287 runs</li>
</ol>

With reversed, the items are numbered 3, 2, 1, which suits a countdown. Use type when the numbering style is part of the meaning, for example when a question paper refers to "part (b)". For purely visual styles, CSS list-style-type is the better tool.

Description lists

A description list, <dl>, holds pairs of terms and descriptions, like a glossary or a set of details. Each term goes in <dt> (description term) and each description in <dd> (description details).

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Description list</title>
</head>
<body>
  <h2>Train ticket details</h2>
  <dl>
    <dt>Passenger</dt>
    <dd>Priya Sharma</dd>
    <dt>From</dt>
    <dd>Lucknow</dd>
    <dt>To</dt>
    <dd>New Delhi</dd>
    <dt>Coach and berth</dt>
    <dd>B2, berth 34 (lower)</dd>
  </dl>
</body>
</html>

A term can have more than one description, and several terms can share one description. If you want to style each pair as a group, you may wrap each <dt> and its <dd> in a <div> inside the <dl>.

Lists inside lists

A list item can contain another complete list. This is called nesting. The inner list goes inside an <li>, after the item's text, never directly inside the outer <ul> or <ol>.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Nested lists</title>
</head>
<body>
  <h2>Class 10 syllabus</h2>
  <ul>
    <li>Science
      <ul>
        <li>Chemical reactions</li>
        <li>Light and reflection</li>
      </ul>
    </li>
    <li>Maths
      <ol>
        <li>Real numbers</li>
        <li>Polynomials</li>
      </ol>
    </li>
  </ul>
</body>
</html>

Notice that the </li> for "Science" comes after its inner list closes. Browsers change the bullet style for nested unordered lists so the levels are easy to see. Keep nesting to two or three levels; deeper lists are hard to read.

Lists for navigation

A site menu is a list of links, so it is very often written as a <ul> inside a <nav> element. Screen readers then announce it as a list and say how many items it has, which helps users get their bearings.

<nav>
  <ul>
    <li><a href="index.html">Home</a></li>
    <li><a href="courses.html">Courses</a></li>
    <li><a href="contact.html">Contact</a></li>
  </ul>
</nav>

CSS can remove the bullets and lay the items out in a row. You will see <nav> in Semantic HTML and list styling in Styling Lists & Tables.

Common mistakes

• Putting other elements directly inside <ul> or <ol>. Only <li> elements may be direct children. Put headings or paragraphs inside an <li> or outside the list.
• Nesting a list in the wrong place. The inner list must sit inside an <li>, not between two <li> elements.
• Typing numbers by hand. <li>1. Boil water</li> inside an <ol> shows the number twice. Let the browser count.
• Using a list only for indentation. A list must contain list items; use CSS to indent other content.
• Using <br> instead of a list. Lines separated by <br> are not a list to a screen reader. If it is a list, mark it up as one.

Key points

• Use <ul> when order does not matter and <ol> when it does; each item goes in <li>.
• Browsers number ordered lists automatically and renumber when items change.
• start, reversed, type and value control ordered list numbering.
• Use <dl> with <dt> and <dd> for term and description pairs.
• A nested list goes inside an <li>, after that item's text.
• Navigation menus are usually a <ul> of links inside <nav>.

<h1>Meera's Lemon Rice</h1>
<h2>Ingredients</h2>
<ul>
  <li>2 cups cooked rice</li>
  <li>1 lemon</li>
  <li>A handful of peanuts</li>
  <li>Curry leaves and salt</li>
</ul>
<h2>Steps</h2>
<ol>
  <li>Heat oil in a pan and roast the peanuts.</li>
  <li>Add the tempering spices:
    <ul>
      <li>Mustard seeds</li>
      <li>Urad dal</li>
      <li>Dried red chilli</li>
    </ul>
  </li>
  <li>Add curry leaves, turmeric and the rice. Mix well.</li>
  <li>Switch off the heat and squeeze in the lemon juice.</li>
</ol>
<dl>
  <dt>Serves</dt>
  <dd>3 people</dd>
  <dt>Cooking time</dt>
  <dd>15 minutes</dd>
</dl>