Group related information with lists

One idea at a time

A list says that several pieces of information belong together. A shopping list is a collection; a recipe is a sequence. Their relationship matters more than whether you prefer bullets or numbers. Choosing the appropriate HTML gives browsers and assistive technology useful information about the group.

An unordered list uses ul and contains li elements. Use it when rearranging the items does not change their meaning. An ordered list uses ol with the same li elements, but their order matters. The browser generates the markers; you do not type a number at the start of each item.

A description list uses dl with dt for a term or name and dd for its description or value. It suits a small glossary or a set of facts. It does not use li. Start with a single term and description before adding more pairs.

Make a bullet list: ul and li

Use an unordered list when you have a group of items and their order does not matter. Seeds and soil are both supplies: swapping them does not change what you need.

<ul>
  <li>Seeds</li>
  <li>Soil</li>
</ul>

Read this from the outside inward: <ul> starts the list, <li>Seeds</li> creates its first item, and <li>Soil</li> creates its second item. </ul> ends the whole list. The result is two bullet points: Seeds and Soil. The browser supplies the bullets; do not type them into the item text.

To add Water, put <li>Water</li> on a new line before </ul>. A new line in your editor alone does not create another item: the li element does. Indentation makes the code easier to read, but does not create the list.

Make a numbered list: ol and li

Use an ordered list when the sequence matters, such as instructions. Fill a pot before planting seeds, then water them. Changing that order changes the instructions.

<ol>
  <li>Fill the pot.</li>
  <li>Plant the seeds.</li>
  <li>Water gently.</li>
</ol>

The result is 1. Fill the pot, 2. Plant the seeds, and 3. Water gently. The numbers are generated from the items' positions inside ol. Insert another li between two steps and the browser renumbers the following steps for you.

The outer tag chooses the list type: ul for a collection, ol for a sequence. The inner li tags identify the individual items in either type. Close each item before starting the next one, and close the list after its last item. An h2 can introduce the list, but it stays outside ul or ol.

In the interactive example below, compare the supplies and planting steps. Notice which outer tag changes and which item tag stays the same.

Pair a term with its description: dl, dt, and dd

Sometimes a list is neither a collection of supplies nor a sequence of steps. A glossary pairs each word with its meaning. HTML calls this a description list. It can also pair names with values, such as a plant name and its watering needs.

<dl>
  <dt>Seedling</dt>
  <dd>A young plant grown from a seed.</dd>
  <dt>Compost</dt>
  <dd>Decomposed organic material.</dd>
</dl>

Read the first pair as: Seedling means a young plant grown from a seed. The next dt starts another term, Compost, and the following dd describes it. In this simple example, each term has one description. dt and dd are siblings inside dl; do not place dd inside dt or wrap either in li.

Browsers usually indent descriptions beneath their terms. That appearance helps you see the pairs, but the relationship comes from the HTML, not the indentation. Use ul or ol with li for ordinary items; use dl with dt and dd when you need names paired with descriptions.

In the interactive example below, choose A term and its description. Match each visible term to its dt and each explanation to its dd. For your own glossary, add another dt followed by a dd before the closing dl tag.

Walk through an example

<h2>Supplies</h2>
<ul>
  <li>Seeds</li>
  <li>Soil</li>
</ul>
<h2>Planting steps</h2>
<ol>
  <li>Fill the pot.</li>
  <li>Plant the seeds.</li>
  <li>Water gently.</li>
</ol>

The supplies are an unordered collection, while the planting instructions depend on a sequence. Each list item opens and closes inside its own list. Add another planting step between the first two and the browser updates the numbers automatically. The headings name the groups but are outside the list containers.

See it happen: try a small change

<h2>Supplies</h2>
<ul>
  <li>Seeds</li>
  <li>Soil</li>
</ul>

Keep nested information inside its parent item

A nested list adds detail to one item. If Tools contains a smaller list of Shovel and Watering can, put the inner ul before the closing li for Tools. Indentation makes that ownership visible in the source. A second list beside the item would not express the same parent-child relationship.

For an ordered list that continues an earlier sequence, start can set its first number. For example, <ol start="4"> begins its numbering at 4. Use that when the numbering itself conveys information. Leave decorative marker choices for CSS later. A list should remain meaningful even if its markers look different in another browser or stylesheet.

<ul>
  <li>Tools
    <ul>
      <li>Shovel</li>
      <li>Watering can</li>
    </ul>
  </li>
</ul>

Try it in your browser

Put the list fragments inside body in your existing document. Save and refresh after adding one li. Check that the browser supplies the marker. For a nested list, find the outer item’s closing li in the editor and place the inner list before it.

A common wrong turn

A paragraph beginning with a dash only looks like a list item. It does not become an li. Similarly, placing an inner list after the closing parent li loses the intended nesting. Inspect the opening and closing tags rather than adding spaces to imitate the result.

Change one thing

Insert and remove one ordered item. Then compare a glossary with the same text in an unordered list. Explain what the term-description structure adds.

Go to the source

• MDN: Group related information with lists ↗

Examples are authored for Tuklas and checked with code and reference documentation. This is not a claim of independent human review. Suggest a correction.