Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

List

Version 8.1.2GithubStorybook

A List is a set of text objects in a bulleted or numbered format.

Component preview theme
<UnorderedList>
<ListItem>
Trans black lives matter
</ListItem>
<ListItem>
Queer black lives matter
</ListItem>
<ListItem>
Poor black lives matter
</ListItem>
<ListItem>
Young black lives matter
</ListItem>
<ListItem>
Old black lives matter
</ListItem>
<ListItem>
All black lives matter
</ListItem>
</UnorderedList>

Guidelines

Guidelines page anchor

Lists can be ordered or unordered. If the order of the list items matters for context to the user, an ordered list should be used. If the meaning of the list is not changed based on the order of the items, an unordered list should be used.

About Lists

About Lists page anchor

Lists are a number of connected list items that are printed consecutively, typically one after the other. Lists can be ordered, using numbers as an indicator to the reader, or unordered with bullet points.

  • Ordered lists are displayed with a preceding number.
  • Unordered lists are displayed with a preceding bullet point.
  • Lists can be nested as deeply as needed, and they may alternate between ordered and unordered.
  • Lists should align with the font-size, font-weight, and line-height of paragraphs, but are styled with bullets or numbers.
  • Lists can have similar children elements as paragraphs to provide emphasis on a certain word or phrase.
  • ListItems should always have an OrderedList or UnorderedList parent component.
  • Nested ListItems should be wrapped in their own, new OrderedList or UnorderedList parent component. For example:
<OrderedList>
  <ListItem>
    Text of the parent list item
    <OrderedList>
      <ListItem>Nested list item</ListItem>
    </OrderedList>
  </ListItem>
</OrderedList>

An unordered list is the default variant for List.

Use unordered lists to display a basic list of items related to a particular topic. Use Heading and/or body text preceding the list to introduce the linked topic.

Component preview theme
<UnorderedList>
<ListItem>
Tamir Rice
</ListItem>
<ListItem>
Philando Castile
</ListItem>
<ListItem>
Trayvon Martin
</ListItem>
<ListItem>
Breonna Taylor
</ListItem>
<ListItem>
Shantel Davis
</ListItem>
<ListItem>
Walter Scott
</ListItem>
<ListItem>
Mario Gonzalez
</ListItem>
</UnorderedList>

Use ordered list to display a numbered list of items.

Component preview theme
<OrderedList>
<ListItem>
Tamir Rice
</ListItem>
<ListItem>
Philando Casitle
</ListItem>
<ListItem>
Trayvon Martin
</ListItem>
<ListItem>
Breonna Taylor
</ListItem>
<ListItem>
Shantel Davis
</ListItem>
<ListItem>
Walter Scott
</ListItem>
<ListItem>
Mario Gonzalez
</ListItem>
</OrderedList>

List items can be nested within other list items. To do so create a new list as a child to a ListItem.

Component preview theme
<div>
<OrderedList>
<ListItem>
Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
<UnorderedList marginBottom="space0">
<ListItem>
Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
</ListItem>
<ListItem>
Duis mollis, est non commodo luctus.
</ListItem>
</UnorderedList>
</ListItem>
<ListItem>
Duis mollis, est non commodo luctus.
</ListItem>
</OrderedList>
<UnorderedList>
<ListItem>
Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
<OrderedList marginBottom="space0">
<ListItem>
Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
</ListItem>
<ListItem>
Duis mollis, est non commodo luctus.
</ListItem>
</OrderedList>
</ListItem>
<ListItem>
Duis mollis, est non commodo luctus.
</ListItem>
</UnorderedList>
</div>

Start each list item with the same part of speech, usually a noun or verb. This makes the list "parallel."

Do not use a period at the end of list items unless they are complete sentences. Do not use commas or ellipses at the end of list items.

Avoid listing very long lists. Where possible, make a big list into smaller ones with explanatory Headings.

  • Point one
  • Point two
  • Point three
Do

Use a list when you have more than one item or point.

  • Point one
Don't

Don’t use lists for a single item.

Animals

  • Mammals
    • Cat
    • Dog
  • Birds
    • Chicken
    • Turkey
Do

Use nested lists to provide additional clarity or instruction on specific topics.

Animals

  • Mammals

    Groceries

    • Milk
    • Butter
  • Birds
    • Chicken
    • Turkey
Don't

Don’t nest lists if the nested content is unrelated to the higher level topic.