How to create a list

Learn about the 3 different types of lists and how to create them.

What is a list?

A list is a group of related items.

Typically, lists are visually presented vertically, with each item:

• starting a new line
• preceded by a list marker, such as a dot (bullet), a number or a letter, that indicates that this is 1 item in a list of related items.

However, lists are also used to provide information about the underlying structure of some web content and, while these types of lists are programmatically marked up as lists, they do not necessarily look like typical lists.

• A website’s main navigation menu is commonly marked up as a list of links but visually displayed horizontally across the screen with no list marker before each link.
• A sidebar with a list of links to different subsections of the page is visually presented as a vertical list, but with no list marker before each link.

How lists help users find information quickly

Lists make content easier to scan. They help:

• make key information stand out
• break up and shorten large blocks of text
• make complex information easier to understand.

Lists are also very helpful to screen reader users. Screen reader software will identify all lists on a page and users can use shortcuts to jump from list to list. It might also identify:

• how many items are in a list
• the position of the item (for example, “3 of 7”) in the list currently being read.

Sighted users can determine all of this information through the way that lists are visually presented. However, people who rely on screen reader software can only determine the structure of content in lists if the information is provided programmatically through semantic HTML markup.

Types of lists

In web content, there are 3 main types of list:

• ordered list: A list where the order of the items is meaningful — for example, a numbered list of instructions for a recipe
• unordered list: A list where the order of the items is not important or meaningful — for example, a bulleted list of ingredients for a recipe
• description list: A list of items where there is a description or definition for each item — for example, a glossary.

Ordered and unordered lists

Whenever possible, use native HTML to create an ordered or unordered list.

Native HTML ordered and unordered lists

To create an ordered list in HTML, use the <ol> element. To create an unordered list, use the <ul> element.

Each list item within the <ol> or <ul> is created using the <li> element.

As a general rule, only <li> elements are allowed within an <ol> or <ul> element. The only exceptions are <script> and <template> elements.

For more on native HTML ordered lists, see:

• Ordered list — Web Accessibility Tutorials — W3C
• <ol>: The Ordered List element — MDN Web Docs
• The ol element — HTML Living Standard.

For more on native HTML unordered lists, see:

• Unordered list — Web Accessibility Tutorials — W3C
• <ul>: The Unordered List element — MDN Web Docs
• The ul element — HTML Living Standard.

Nested lists

Lists can be nested within other lists. That is, a list item within an ordered or unordered list can itself include another ordered or unordered list. See Nesting a list — <ul>: The Unordered List element — MDN Web Docs.

Custom ordered and unordered lists

In almost all cases, it’s recommended to use native HTML list elements.

Sometimes, however, a developer will repurpose other HTML elements to create a list. This requires the use of the ARIA list and listitem roles.

For more information on creating custom ordered and unordered lists, see:

• ARIA Lists — Scott O’Hara
• ARIA: list role — MDN Web Docs
• list role — WAI-ARIA — W3C
• ARIA: listitem role — MDN Web Docs
• listitem role — WAI-ARIA — W3C.

Styling list markers with CSS

You can change the list markers used for ordered and unordered lists using CSS. You can also replace the marker with an image or remove it entirely.

For more details, see:

• CSS Lists, Markers, And Counters — Smashing Magazine
• list-style — CSS: Cascading Style Sheets — MDN Web Docs
• ::marker — CSS: Cascading Style Sheets — MDN Web Docs

Description or association lists

A description list, also known as an association or definition list, is a collection of name-value groups.

A name-value group can comprise:

• a single term associated with multiple descriptions
• multiple terms associated with a single description
• multiple terms associated with multiple descriptions.

Description lists can be used for any content comprising name-value groups, such as:

• glossaries
• rules in a game
• information like price, colour, and size for products on sale
• frequently asked questions (FAQs).

Native HTML description lists

Use the <dl> element to identify a list of name-value groups. Within the <dl>, each name-value group is defined by:

• one or more <dt> elements to identify the name(s) or term(s) in the group
• one or more <dd> element to identify the value(s) or description(s) associated with the name(s) or term(s) in the group.

As a general rule, only <dt> and <dd> elements are allowed within a <dl> element. However, groups of <dt> and <dd> elements can be wrapped in <div> elements to allow styles or other attributes to be applied to those groups. Otherwise, <script> and <template> are the only other elements that can appear within a <dl>.

For more on native HTML description lists, see:

• Description lists — Web Accessibility Tutorials — W3C
• On the <dl> — Ben Myers
• The dl element — HTML Living Standard

Custom description lists

Support for custom description or association lists does not currently exist. Explicit ARIA roles for such lists are being defined in version 1.3 of the W3C’s ARIA specification. That specification will not be an official W3C recommendation for some time, although browser support for the roles might always come sooner.

For more, see the associationlist role — WAI-ARIA 1.3 Editor’s Draft — W3C.