List

Lists are used to organize a group of related text elements.

Status

Figma UI Kit	PublishedElement can be used in production
Vanilla	PublishedElement can be used in production
Angular	PublishedElement can be used in production
React	In backlogElement is in backlog
Documentation	In progressElement design and development in progress

What's new

List was previously named “Lists.” This component has been redesigned to the updated font ramp and color palette, in addition to accessibility enhancements, and now includes two text styles.

When to use

List and table are not used for the same purpose. Identifying the right use case will make the experience clear for all users, particularly for those with cognitive and learning disabilities, or those using screen readers.

Component	Use case
List	A list presents a group of related information in a scannable format.
Table	A table displays complex groups of information for the purpose of reference, comparison, or choice.

Anatomy

The parts of a list, labeled 1 through 2. — Prefix: either a bullet or a number.

List item: static text or links.

Usage

Usage is very often correlated with list kinds. Ensure the kind matches the user’s expectations of the experience to avoid confusion. Users would not expect to see an ordered list for a group of discrete items.

Related items

List can be used to show semantically related items or options. For example, a “Ports” header under a product’s technical specifications section, listing USB, power adapter, ethernet, and other included ports. List items may also be links, such as a list of resources attached to an article for further reading.

Process documentation

Complex processes may be hard for a user to digest and thus require a list of steps. This could include the actions that must be taken to enroll in a program, or an escalation of steps to take to correct a problem.

Navigation

Navigational items are often shown as a list of links to allow users to easily scan an overview of available pages.

Kinds

Lists are available with or without a prefix.

An image showing an ordered list with numbered styling. — **Ordered:** An ordered list contains items that are sequential or in order of priority, such as steps in a process. List items are marked by a number.

An image showing an unordered list with bullet point styling. — **Unordered**: An unordered list contains related items that don’t rely on a sequential order. List items are preceded by a bullet point.

An image showing an unstyled list with no bullet point or number styling. — **Unstyled**: An unstyled list is an unordered list without bullet point styling, such as sidebar navigation. Unstyled lists still have left-padding, so list items will appear indented.

Options

In the Figma UI kit, list is available with two text styles: body 1 and body 2. You can read more about the font ramp on the Typography foundations page.

An image showing a list in body 1 font size.

An image showing a list in body 2 font size.

Text Style	Use case
Body 1	Larger list text that pairs with Display 1 titles and larger body text. Read more about use cases in the font ramp section of the Typography page.
Body 2 (default)	The default text style for list text.

Standards

Accessibility

Vertically-stacked (listed) links should have a line height of 24 pixels or greater
This guideline creates a minimum distance between touch targets for anyone who experiences difficulties with fine motor control. The simplest and easiest way to meet this guideline is to apply the default body style (16 pixels with a line height of 24 pixels) or larger to your stacked links.

If the links are the small variant (12 pixels) or have a custom type style applied, ensure they have a minimum 24 pixel line-height. While inline links are exempt from this requirement, styling them with 16 pixel default body or greater is still recommended.
WCAG 2.1: 2.5.8 Target Size (Minimum)

Content

Formatting
Keep formatting consistent. Whether list items are written as sentences or fragments, keep all items in the same format.
Do:
Things to do on vacation:
Take a walk on the beach.
Explore a historic town.
Sleep in until noon.
Don’t:
Things to do on vacation:
take a walk on the beach
explore a historic town
Sleep in until noon.

Repetition
Avoid repeating the first word in each list item.
Do:
Reasons to take a break:
Take a shower.
Go for a walk.
Enjoy a short nap.
Don’t:
Reasons to take a break:
Take a shower.
Take a walk.
Take a nap.

List item order
Only use ordered lists when the order of items is important.
Do:
Product return process:
Place items in original packaging
Contact Customer Returns
Add RMA to shipping label
Drop off at UPS or FedEx location
Don’t:
How to contact Customer Support:
Email
Phone
By mail
In person

Capitalization
Begin each list item with a capital letter if it is a complete sentence. If the list item is a fragment, it may be sentence case following a colon in the sentence preceding the list.

Punctuation
If list items are complete sentences, they should end with a period or the appropriate punctuation. If the list item is a fragment, punctuation is not required.

Live demo

This demo lets you interact with the component and view the code. To see other interactive examples of this component or for additional developer documentation, visit Storybook.

You are now entering a live demo of the component.

<ul class="dds__list">
  <li>List item text</li>
  <li>
    List item with an
    <a href="#">inline link</a>
  </li>
  <li>To prevent overflow, list items will wrap to the next line when their container contracts</li>
  <li><a href="#">List item inline link</a></li>
  <li>To prevent overflow, list items will wrap to the next line when their container contracts</li>
  <li>
    List item with an
    <a href="#">inline link</a>
  </li>
  <li>To prevent overflow, list items will wrap to the next line when their container contracts</li>
</ul>

Copy code

Visit the list demo and code in Vanilla.

Visit Storybook

Visit the list demo and code in Angular.

Visit Storybook

List

Status

Contents

What's new

When to use

Anatomy

Contents

Contents

Usage

Related items

Process documentation

Navigation

Kinds

Options

Standards

Accessibility

Content

Contents

Contents

Live demo

You are now entering a live demo of the component.

Vanilla

Angular

Contents

List

Status

Contents

What's newCopy link to this section

When to useCopy link to this section

AnatomyCopy link to this section

Contents

What's new

When to use

Anatomy