Lists

Three kinds of list

Lists are everywhere on the web: menus, steps, features, search results, comment threads. HTML has three list types, and choosing the right one is about meaning, just like headings.

<h3>Packing list</h3>
<ul>
  <li>Passport</li>
  <li>Charger</li>
  <li>Water bottle</li>
</ul>

<h3>Making tea</h3>
<ol>
  <li>Boil the water.</li>
  <li>Add the tea leaves and simmer for two minutes.</li>
  <li>Add milk and sugar, then strain.</li>
</ol>

• ul (unordered list): the order does not matter. Shuffling the packing list changes nothing. Browsers show bullets.
• ol (ordered list): the order matters. Doing the tea steps in a different order gives you a different drink. Browsers show numbers.

Each item is an li (list item), whichever kind of list it is in.

The one strict rule

A ul or ol may only have li elements as direct children. Headings, paragraphs and divs go inside an li, never directly inside the list.

<!-- Wrong: a paragraph directly inside the list -->
<ul>
  <p>Fruit</p>
  <li>Apple</li>
</ul>

<!-- Right: put the label before the list, or inside an li -->
<p>Fruit</p>
<ul>
  <li>Apple</li>
</ul>

Inside an li you may put almost anything: links, images, paragraphs, even another list.

Nested lists

A sub-list belongs to one item, so it goes inside that item's li, after its text:

<ul>
  <li>Fruit
    <ul>
      <li>Mango</li>
      <li>Guava</li>
    </ul>
  </li>
  <li>Vegetables
    <ol>
      <li>Wash</li>
      <li>Chop</li>
    </ol>
  </li>
</ul>

Notice that the closing </li> for "Fruit" comes after the inner list. A very common mistake is to close the li first and put the sub-list between two items, which breaks the rule above.

You can nest ol inside ul and the other way round. Keep nesting shallow, though: two levels are easy to follow, four levels usually mean the content needs restructuring.

Controlling the numbers

Ordered lists accept a few useful attributes:

<ol start="4">
  <li>Fourth step, continuing an earlier list</li>
  <li>Fifth step</li>
</ol>

<ol reversed>
  <li>Bronze</li>
  <li>Silver</li>
  <li>Gold</li>
</ol>

<ol type="a">
  <li>Option a</li>
  <li>Option b</li>
</ol>

• start="4" begins counting at 4, handy when steps are split by an image or a note.
• reversed counts down, as in a top-ten countdown.
• type switches between 1, a, A, i and I. Use it when the letter or numeral is part of the meaning, such as clauses in a contract; for purely visual changes, CSS list-style-type is better.

Description lists

A description list pairs a term (dt) with its description (dd):

<dl>
  <dt>Processor</dt>
  <dd>8-core, 2.4 GHz</dd>
  <dt>Battery</dt>
  <dd>5,000 mAh</dd>
  <dd>Fast charging, 33 W</dd>
</dl>

A term can have more than one description, as the battery does here. Description lists suit glossaries, product specifications, metadata ("Author: ... Published: ...") and simple FAQs.

Lists for navigation

Most website menus are a ul of links inside a nav element. It tells assistive technology "this is navigation, and it has five items", which helps people decide whether to explore it or skip it. CSS later turns the vertical bullet list into a horizontal menu bar.

<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>

Common mistakes

• Typing your own bullets or numbers, such as "1." or "•" inside list items or paragraphs. You get them twice, and screen readers do not know it is a list.
• Non-li children in a ul or ol.
• Closing the parent li before a nested list.
• Choosing ol for looks. If you only want numbers on screen but the order is meaningless, use ul and style it.

When you rework a long list, the Text Diff tool is a quick way to see exactly which items changed between two versions.

Exercise

Build a "How to make a website" page section with an ordered list of four steps. Step 2, Write the HTML, should contain a nested unordered list of three files (index.html, about.html, contact.html). After the steps, add a description list explaining two terms: HTML and Browser.

<ol>
  <li>Plan the pages</li>
  <li>Write the HTML
    <ul>
      <li>index.html</li>
      <li>about.html</li>
      <li>contact.html</li>
    </ul>
  </li>
  <li>Add CSS</li>
  <li>Publish it</li>
</ol>

<dl>
  <dt>HTML</dt>
  <dd>The language that describes the structure of a web page.</dd>
  <dt>Browser</dt>
  <dd>The program that downloads web pages and displays them.</dd>
</dl>