ForgeLearn
|$ curl https://forge-ai.dev/api/markdown?path=docs/html/lists
$cat docs/html-lists.md
updated This week·25 min read·published

HTML Lists

◆HTML◆Lists◆Beginner◆Beginner
Introduction

HTML provides three types of lists: unordered lists (<ul>) for items without a specific order, ordered lists (<ol>) for sequential steps or rankings, and description lists (<dl>) for term-definition pairs. Lists are among the most commonly used HTML structures, appearing in navigation menus, feature lists, step-by-step instructions, glossaries, and more.

Beyond their visual presentation, lists carry important semantic meaning. Screen readers announce the number of items in a list and allow users to navigate between items — making lists one of the most accessible patterns in HTML when used correctly.

ℹ

info

The list role is implicit on <ul>, <ol>, and <dl> elements. Never use role="list" on a <div> as a replacement — use the native elements for full accessibility and semantics.
Unordered Lists

Unordered lists are used when the order of items does not matter. Each item is wrapped in an <li> element. Browsers render unordered lists with bullet markers by default. The list-style-type CSS property controls the marker style.

unordered-lists.html
HTML
1<!-- Basic unordered list -->
2<ul>
3 <li>Apples</li>
4 <li>Bananas</li>
5 <li>Cherries</li>
6 <li>Dates</li>
7</ul>
8
9<!-- Nested unordered list -->
10<ul>
11 <li>Fruits
12 <ul>
13 <li>Apples</li>
14 <li>Bananas</li>
15 </ul>
16 </li>
17 <li>Vegetables
18 <ul>
19 <li>Carrots</li>
20 <li>Broccoli</li>
21 </ul>
22 </li>
23</ul>
24
25<!-- Unordered list with custom bullet styles -->
26<ul style="list-style-type: square;">
27 <li>Square bullet item</li>
28 <li>Another square item</li>
29</ul>
30
31<ul style="list-style-type: circle;">
32 <li>Circle bullet item</li>
33 <li>Another circle item</li>
34</ul>
35
36<ul style="list-style-type: none;">
37 <li>No bullet — useful for navigation</li>
38 <li>Use padding to align text</li>
39</ul>

Live preview of unordered lists with different bullet styles:

preview
🔥

pro tip

For navigation menus, set list-style-type: none and remove default padding. Use display: flex on the <ul> to create horizontal navigation. The <nav> element wrapping a list provides the best accessibility semantics.
Ordered Lists

Ordered lists are used when the sequence of items matters — steps in a recipe, ranking of results, or chronological events. The <ol> element supports three key attributes: type controls the numbering style, start sets the starting number, and reversed counts downward.

AttributeValuesExampleRenders As
type1 | A | a | I | itype="A"A, B, C, D...
startintegerstart="5"5, 6, 7, 8...
reversedbooleanreversed3, 2, 1...
valueinteger (on <li>)value="10"Override item number
ordered-lists.html
HTML
1<!-- Default numbered list -->
2<ol>
3 <li>Preheat oven to 350°F</li>
4 <li>Mix dry ingredients</li>
5 <li>Add wet ingredients</li>
6 <li>Bake for 30 minutes</li>
7</ol>
8
9<!-- Uppercase letters -->
10<ol type="A">
11 <li>First item</li>
12 <li>Second item</li>
13 <li>Third item</li>
14</ol>
15
16<!-- Lowercase Roman numerals -->
17<ol type="i">
18 <li>Introduction</li>
19 <li>Methodology</li>
20 <li>Results</li>
21 <li>Conclusion</li>
22</ol>
23
24<!-- Starting at a specific number -->
25<ol start="5">
26 <li>This item starts at 5</li>
27 <li>This is item 6</li>
28 <li>This is item 7</li>
29</ol>
30
31<!-- Reversed (countdown) -->
32<ol reversed>
33 <li>Top priority</li>
34 <li>Second priority</li>
35 <li>Third priority</li>
36</ol>
37
38<!-- Overriding specific item values -->
39<ol>
40 <li>Item 1</li>
41 <li>Item 2</li>
42 <li value="10">Jump to item 10</li>
43 <li>Item 11 (continues from 10)</li>
44</ol>
45
46<!-- Nested ordered list -->
47<ol>
48 <li>Step 1: Setup
49 <ol type="a">
50 <li>Install dependencies</li>
51 <li>Configure environment</li>
52 </ol>
53 </li>
54 <li>Step 2: Build</li>
55 <li>Step 3: Deploy</li>
56</ol>

Live preview of ordered list attributes:

preview
⚠

warning

The type attribute on <ol> is presentational. It does not change the semantic meaning of the list. Screen readers will announce the item number, not the letter or Roman numeral. Use CSS list-style-type instead for consistent behavior across browsers.
Description Lists

Description lists (<dl>) group term-definition pairs. Each term uses <dt> (description term) and each definition uses <dd> (description details). Unlike <ul> and <ol>, a <dl> can contain multiple terms per definition and vice versa. Description lists are ideal for glossaries, metadata, key-value pairs, and FAQs.

description-lists.html
HTML
1<!-- Basic description list -->
2<dl>
3 <dt>HTML</dt>
4 <dd>HyperText Markup Language — the standard markup language for creating web pages.</dd>
5
6 <dt>CSS</dt>
7 <dd>Cascading Style Sheets — a stylesheet language for describing the presentation of HTML.</dd>
8
9 <dt>JavaScript</dt>
10 <dd>A high-level programming language that enables interactive web pages.</dd>
11</dl>
12
13<!-- Multiple terms for one definition -->
14<dl>
15 <dt>Color</dt>
16 <dt>Colour</dt>
17 <dd>The visual perception of light wavelengths reflected from a surface.</dd>
18</dl>
19
20<!-- One term with multiple definitions -->
21<dl>
22 <dt>Browser</dt>
23 <dd>A software application for accessing the World Wide Web.</dd>
24 <dd>A person who browses or inspects items in a casual manner.</dd>
25</dl>
26
27<!-- Glossary with abbreviations -->
28<dl>
29 <dt><abbr title="Application Programming Interface">API</abbr></dt>
30 <dd>A set of defined rules that enable different software to communicate.</dd>
31
32 <dt><abbr title="Document Object Model">DOM</abbr></dt>
33 <dd>A programming interface for HTML and XML documents, representing the page as a tree structure.</dd>
34</dl>
35
36<!-- FAQ-style description list -->
37<dl>
38 <dt>How do I create a list in HTML?</dt>
39 <dd>Use &lt;ul&gt; for unordered lists, <ol&gt; for ordered lists, and <dl&gt; for description lists.</dd>
40
41 <dt>Can I nest lists?</dt>
42 <dd>Yes, you can nest any list type inside any other list type.</dd>
43
44 <dt>Are lists accessible?</dt>
45 <dd>Yes — native list elements are announced by screen readers with item count and position.</dd>
46</dl>

Live preview of a styled description list:

preview
ℹ

info

Description lists are underused. They are the semantically correct way to mark up glossaries, metadata, configuration key-value pairs, and FAQ sections. Avoid using <ul> or <div> with custom styles for these patterns — use a <dl>.
Nesting Lists

Lists can be nested to any depth and can mix list types. A nested list must be placed inside an <li> element — never directly inside a <ul>, <ol>, or <dl>. This rule applies to all list types.

nesting-lists.html
HTML
1<!-- Mixed nested list: ordered inside unordered -->
2<ul>
3 <li>Research phase
4 <ol>
5 <li>Gather requirements</li>
6 <li>Analyze competitors</li>
7 <li>Define scope</li>
8 </ol>
9 </li>
10 <li>Development phase
11 <ol>
12 <li>Design architecture</li>
13 <li>Implement features</li>
14 <li>Write tests</li>
15 </ol>
16 </li>
17 <li>Release phase
18 <ol>
19 <li>Deploy to staging</li>
20 <li>Run integration tests</li>
21 <li>Deploy to production</li>
22 </ol>
23 </li>
24</ul>
25
26<!-- Deep nesting: multi-level table of contents -->
27<ol type="I">
28 <li>Introduction
29 <ol type="A">
30 <li>Background
31 <ol type="1">
32 <li>Problem statement</li>
33 <li>Related work</li>
34 </ol>
35 </li>
36 <li>Objectives</li>
37 </ol>
38 </li>
39 <li>Methodology
40 <ol type="A">
41 <li>Data collection</li>
42 <li>Analysis</li>
43 </ol>
44 </li>
45</ol>
✓

best practice

Avoid nesting lists more than three levels deep. Deeply nested lists are difficult to read, hard to style, and create accessibility challenges for screen reader users who must navigate each level. If you need more than three levels, consider restructuring your content.
List Styling

CSS provides several properties to control list appearance. The list-style shorthand property combines list-style-type, list-style-position, and list-style-image. Custom markers can be created using the ::marker pseudo-element or ::before/::after with custom content.

PropertyValuesDescription
list-style-typedisc | circle | square | decimal | lower-roman | upper-roman | lower-alpha | upper-alpha | noneMarker style
list-style-positioninside | outsideMarker position relative to content
list-style-imageurl(...) | noneCustom image as marker
::markerCSS propertiesStyle the marker pseudo-element
list-styling.css
CSS
1/* Custom bullet styles */
2ul.custom-bullets {
3 list-style-type: none;
4 padding-left: 0;
5}
6
7ul.custom-bullets li {
8 padding-left: 20px;
9 position: relative;
10}
11
12ul.custom-bullets li::before {
13 content: "\2713";
14 color: #00FF41;
15 position: absolute;
16 left: 0;
17}
18
19/* Marker pseudo-element styling */
20li::marker {
21 color: #00FF41;
22 font-weight: bold;
23}
24
25/* Image as bullet */
26ul.images {
27 list-style-image: url("bullet.svg");
28}
29
30/* Inside vs outside position */
31ol.outside {
32 list-style-position: outside;
33}
34
35ol.inside {
36 list-style-position: inside;
37}
38
39/* Horizontal list (flexbox) */
40ul.horizontal {
41 list-style: none;
42 display: flex;
43 gap: 16px;
44 padding: 0;
45}
46
47/* Vertical navigation list */
48ul.nav {
49 list-style: none;
50 padding: 0;
51 margin: 0;
52}
53
54ul.nav li {
55 border-bottom: 1px solid #eee;
56}
57
58ul.nav li a {
59 display: block;
60 padding: 8px 12px;
61 text-decoration: none;
62 color: #333;
63}
64
65ul.nav li a:hover {
66 background: #f5f5f5;
67}

Live preview of custom list styling:

preview
🔥

pro tip

The ::marker pseudo-element only supports a limited set of CSS properties: color, font-size, font-family, font-weight, and a few others. For complex custom markers, use list-style: none with ::before pseudo-elements.
Accessibility

Native HTML lists have built-in accessibility semantics. Screen readers automatically announce the list type (ordered, unordered, or description), the number of items, and the current item position. These announcements help users understand the structure and navigate efficiently.

ElementImplicit RoleScreen Reader Behavior
<ul>listAnnounces "List of X items" and item positions
<ol>listAnnounces "Ordered list of X items" with numbers
<dl>listAnnounces term-definition groups
<li>listitemAnnounces position (e.g., "Item 3 of 5")
<dt>termAnnounced as term in description list
<dd>definitionAnnounced as definition of preceding term
list-accessibility.html
HTML
1<!-- Accessible navigation using lists -->
2<nav aria-label="Main navigation">
3 <ul>
4 <li><a href="/">Home</a></li>
5 <li><a href="/about">About</a></li>
6 <li><a href="/services">Services</a></li>
7 <li><a href="/contact">Contact</a></li>
8 </ul>
9</nav>
10
11<!-- Breadcrumb navigation -->
12<nav aria-label="Breadcrumb">
13 <ol>
14 <li><a href="/">Home</a></li>
15 <li><a href="/docs">Documentation</a></li>
16 <li aria-current="page">HTML Lists</li>
17 </ol>
18</nav>
19
20<!-- Accessible checklist with aria attributes -->
21<ul aria-label="Task checklist">
22 <li aria-checked="true">
23 <span role="checkbox" aria-checked="true" tabindex="0">✓</span>
24 Complete requirements
25 </li>
26 <li aria-checked="false">
27 <span role="checkbox" aria-checked="false" tabindex="0">◻</span>
28 Write documentation
29 </li>
30</ul>
31
32<!-- Tab list pattern -->
33<ul role="tablist" aria-label="Documentation tabs">
34 <li role="tab" aria-selected="true" tabindex="0">
35 Overview
36 </li>
37 <li role="tab" aria-selected="false" tabindex="-1">
38 Examples
39 </li>
40 <li role="tab" aria-selected="false" tabindex="-1">
41 API Reference
42 </li>
43</ul>
✓

best practice

Never remove list semantics with role="presentation" on lists that contain interactive elements (like navigation links). Screen readers need the list structure to convey the number of items. Use aria-label on <nav> elements to distinguish multiple navigation regions.
Use Cases

Lists are versatile and appear in nearly every web page. Here are the most common use cases, each with the appropriate list type and implementation approach.

Use CaseList TypeKey Consideration
Primary navigationUnorderedWrap in <nav>, use flexbox for horizontal layout
BreadcrumbsOrderedSequence matters — use <ol> with aria-current
Step-by-step instructionsOrderedUse type/reversed for non-standard numbering
Feature listUnorderedCustom bullets with ::before for checkmarks
Glossary / dictionaryDescriptionUse <dl> with <dt> and <dd>
FAQ sectionsDescription<dt> for questions, <dd> for answers
Metadata key-value pairsDescriptionSemantic and lightweight — ideal for configs
Table of contentsOrdered (nested)Nested <ol> with Roman/alpha styling
Social media feedUnorderedEach post is an <li> in a vertical list
Comment threadsUnordered (nested)Nested <ul> for replies

Live preview of a breadcrumb and navigation pattern using lists:

preview
Best Practices

List Implementation Guide

◆Use &lt;ul&gt; for unordered items, &lt;ol&gt; for ordered/sequential items, and &lt;dl&gt; for term-definition pairs — never use one type for another's purpose
◆Always nest child lists inside an &lt;li&gt; element, never directly inside a parent &lt;ul&gt; or &lt;ol&gt;
◆Use the value attribute on &lt;li&gt; to override numbering in ordered lists when the sequence is non-contiguous
◆Set list-style-type: none and use flexbox/grid for horizontal navigation menus — but keep the &lt;ul&gt; for semantics
◆Provide an aria-label on &lt;nav&gt; elements containing lists when there are multiple navigation regions on the page
◆Use &lt;dl&gt; for glossaries, metadata, and FAQ content — it is semantically richer than header/paragraph pairs
◆Style list markers with ::marker for simple color/font changes, or use ::before with list-style: none for custom content
◆Avoid deeply nested lists beyond 3 levels — restructure content or use a different UI pattern
◆Use aria-current=&quot;page&quot; on the active item in breadcrumbs and navigation lists for screen reader context
◆Do not remove list semantics with role=&quot;presentation&quot; on navigational lists — the item count is useful for all users

Live preview of a best-practice implementation — a styled table of contents using nested ordered lists:

preview
$Blueprint — Engineering Documentation·Section ID: HTML-17·Revision: 1.0
Follow