Fumadocs on TanStack Start

When to use unordered lists, ordered lists, and description lists, and why using list elements matters for navigation and meaning.

Grouping related items together is one of the most common tasks in web content. Ingredients, instructions, navigation links, glossary terms: all of these are lists. HTML provides dedicated elements for them.

The question is not just how to display them visually. It is how to communicate their structure to every user and every tool that reads your page.

The problem with plain paragraphs

Consider a setup guide written as plain text:

<p>First, install Node.js from the official website. Then, open your terminal
and run npm init to create a new project. After that, install your dependencies
with npm install. Finally, start the development server with npm run dev.</p>

Visually this is readable, if slightly dense. But a screen reader user navigating the page by element type cannot find this list. They cannot ask how many steps there are. Screen readers announce list items with positional context: "list, 4 items", "item 1 of 4", "item 2 of 4". That context is completely absent from a paragraph.

Using the correct list elements gives screen reader users the ability to:

Skip past the list entirely
Jump into the list and hear the item count
Navigate item by item with arrow keys

Here is the same content as a proper ordered list:

<ol>
  <li>Install Node.js from the official website.</li>
  <li>Open your terminal and run <code>npm init</code> to create a new project.</li>
  <li>Install your dependencies with <code>npm install</code>.</li>
  <li>Start the development server with <code>npm run dev</code>.</li>
</ol>

Now a screen reader announces "list, 4 items" and gives positional context with each step.

`<ul>`: unordered lists

An unordered list (<ul>) is a list of items where the order does not carry meaning. Swapping two items would not change the list's message.

Each item in a <ul> is an <li> element (list item).

<h2>Ingredients</h2>
<ul>
  <li>2 cups all-purpose flour</li>
  <li>1 teaspoon baking powder</li>
  <li>0.5 teaspoon salt</li>
  <li>1 cup milk</li>
</ul>

Classic uses for <ul>:

Navigation menus (a set of links with no meaningful order)
Product features or benefits
A set of tags or categories
An unranked list of options or examples

The most common use of <ul> on the web is navigation. A site's main navigation is a list of links, and marking it up as a <ul> inside a <nav> communicates that structure to assistive technology.

<nav>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/courses">Courses</a></li>
    <li><a href="/blog">Blog</a></li>
    <li><a href="/contact">Contact</a></li>
  </ul>
</nav>

Screen readers announce this as a navigation landmark with a list inside, giving users context for what they are about to encounter.

`<ol>`: ordered lists

An ordered list (<ol>) is a list of items where the sequence matters. Swapping two items would change the meaning.

<h2>Deploying Your App</h2>
<ol>
  <li>Build the production bundle with <code>npm run build</code>.</li>
  <li>Log in to your hosting provider.</li>
  <li>Upload the contents of the <code>dist</code> folder.</li>
  <li>Set your environment variables in the hosting dashboard.</li>
  <li>Trigger a deployment.</li>
</ol>

Use <ol> for step-by-step instructions, ranked items, a recipe's method, or any list where position carries meaning.

Attributes on `<ol>`

Three attributes let you control how the list is numbered:

start: begin counting at a number other than 1. Useful when a list continues after an interruption.

<p>First, set up your environment:</p>
<ol>
  <li>Install Node.js.</li>
  <li>Install Git.</li>
</ol>

<p>After that, initialise your project:</p>
<ol start="3">
  <li>Run <code>npm init</code>.</li>
  <li>Create an <code>index.html</code> file.</li>
</ol>

reversed: count down instead of up. Useful for a top-ten countdown.

<ol reversed>
  <li>The third most common HTML mistake</li>
  <li>The second most common HTML mistake</li>
  <li>The most common HTML mistake</li>
</ol>
<!-- Renders as: 3. 2. 1. -->

type: change the marker style to letters (a, A) or Roman numerals (i, I). Use this sparingly and only when the list type itself carries meaning (a legal document with Roman numeral sections, for example). For visual styling, prefer CSS list-style-type.

Nested lists

You can nest a list inside a list item to show sub-items. The nested list goes inside the <li>, not after it.

<!-- Correct: nested list inside the parent li -->
<ul>
  <li>
    Front-end technologies
    <ul>
      <li>HTML</li>
      <li>CSS</li>
      <li>JavaScript</li>
    </ul>
  </li>
  <li>
    Back-end technologies
    <ul>
      <li>Node.js</li>
      <li>Python</li>
    </ul>
  </li>
</ul>

Here is the broken version that many beginners write:

<!-- Wrong: nested list is outside the parent li -->
<ul>
  <li>Front-end technologies</li>
  <ul>
    <li>HTML</li>
    <li>CSS</li>
  </ul>
  <li>Back-end technologies</li>
</ul>

This is invalid HTML. The only permitted direct child of <ul> or <ol> is <li>. A browser will often render the broken version visually, but the structure is wrong. Screen readers will not associate the nested items with the parent item, breaking the hierarchical relationship.

You can mix list types when nesting. An ordered list can contain an unordered sub-list, and vice versa.

<ol>
  <li>
    Prepare your ingredients
    <ul>
      <li>Flour, sugar, butter (no particular order)</li>
      <li>Eggs</li>
    </ul>
  </li>
  <li>Preheat the oven to 180°C.</li>
  <li>Mix the dry ingredients first, then the wet.</li>
</ol>

`<dl>`: description lists

A description list (<dl>) groups pairs of terms and their descriptions. It is the right choice for a glossary, a set of metadata fields, or a FAQ.

The structure is: <dl> contains <dt> elements (description terms) and <dd> elements (description details).

<dl>
  <dt>HTML</dt>
  <dd>HyperText Markup Language. The standard language for structuring web content.</dd>

  <dt>CSS</dt>
  <dd>Cascading Style Sheets. Controls the visual presentation of HTML elements.</dd>

  <dt>JavaScript</dt>
  <dd>A programming language that runs in the browser and adds interactivity to pages.</dd>
</dl>

Multiple descriptions for one term

A single term can have more than one description. The extra <dd> elements follow the <dt> directly.

<dl>
  <dt>Repository</dt>
  <dd>A folder tracked by Git that contains the project's files and their history.</dd>
  <dd>Often called a "repo" for short.</dd>
</dl>

Multiple <dt> elements can precede a single <dd>. This is useful for synonyms or aliases.

<dl>
  <dt>Javascript</dt>
  <dt>JS</dt>
  <dd>A programming language that runs in the browser.</dd>
</dl>

Realistic use: metadata fields

Description lists are excellent for structured metadata, like an article's publication details:

<dl>
  <dt>Author</dt>
  <dd>Jane Smith</dd>

  <dt>Published</dt>
  <dd><time datetime="2024-03-15">March 15, 2024</time></dd>

  <dt>Category</dt>
  <dd>HTML Fundamentals</dd>

  <dt>Reading time</dt>
  <dd><time datetime="PT8M">8 minutes</time></dd>
</dl>

Screen readers announce <dl> content with "definition list" context, so users understand they are navigating through term-description pairs.

When not to use `<dl>`

Do not use <dl> just because you want the visual indentation effect of a term on one line and its value indented below. If the content is not genuinely made up of term-description pairs, use a different element and style it with CSS.

<!-- Wrong: these are not term-description pairs, they are steps -->
<dl>
  <dt>Step 1</dt>
  <dd>Install the dependencies.</dd>
  <dt>Step 2</dt>
  <dd>Run the build script.</dd>
</dl>

<!-- Correct: use ol for steps -->
<ol>
  <li>Install the dependencies.</li>
  <li>Run the build script.</li>
</ol>

Common mistakes

Putting block elements between <ul> and <li>. The only valid direct child of <ul> or <ol> is <li>. Do not put <p>, <div>, or any other element directly inside <ul> without wrapping it in <li>.

<!-- Wrong -->
<ul>
  <p>This paragraph is not allowed here.</p>
  <li>Item one</li>
</ul>

<!-- Correct -->
<ul>
  <li>Item one</li>
</ul>

Nesting the inner list outside the parent <li>. The child list goes inside the <li> element, not after its closing tag.

Using <ol> when order does not matter. If swapping two items changes nothing, use <ul>. This distinction helps screen reader users understand whether position carries meaning.

Using <dl> for items that are not term-description pairs. <dl> is for glossaries, metadata, and FAQs. For steps, features, or options, use <ul> or <ol>.

Removing list bullets with CSS and thinking the list is no longer a list. Setting list-style: none removes the visual bullet markers. The element is still a <ul> and screen readers still announce it as a list. This is perfectly fine and very common for navigation menus. The semantic meaning remains even without the visual marker.

Exercise

Build a recipe page with two kinds of lists, and a glossary using a description list.

Lists