Skip to content Skip to navigation Skip to topbar

List

Version 8.2.0Github Storybook

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

<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

Lists can be:

Unordered, when the meaning of the list is not changed based on the order of the items
Ordered, when the order of the list items matters for context to the user.
Ordered Display List, when you need a visually enhanced numbered list to improve the scannability of sequential steps, instructions, or other content within a single screen.

About Lists

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.
Ordered Display lists are displayed with a preceding visually enhanced number.
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.

Ordered Display List vs Progress Steps

Progress Steps

Progress Steps show users an outline of a complex multi-step task across multiple pages.
Progress Steps convey progression and have interactive status states.

Ordered Display List

Ordered Display Lists structure tasks but don’t outline or show progression or status through a multi-step task.
Ordered Display Lists organize complex tasks within a single screen, especially in flows where users need to complete tasks outside of Twilio.

Accessibility

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>

Examples

Unordered List

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.

<UnorderedList>
  <ListItem>
    Tamir Elijah Rice, November 23, 2014 (12 years old)
  </ListItem>
  <ListItem>
    Philando Divall Castile, July 6, 2016 (32 years old)
  </ListItem>
  <ListItem>
    Trayvon Benjamin Martin, February 26, 2012 (17 years old)
  </ListItem>
  <ListItem>
    Breonna Taylor, March 13, 2020 (26 years old)
  </ListItem>
  <ListItem>
    Shantel Davis, June 14, 2012 (23 years old)
  </ListItem>
  <ListItem>
    Walter Scott, April 4, 2015 (50 years old)
  </ListItem>
  <ListItem>
    Mario Gonzalez, April 19, 2021 (26 years old)
  </ListItem>
</UnorderedList>

Ordered List

Use ordered list to display a numbered list of items.

<OrderedList>
  <ListItem>
    Tamir Elijah Rice, November 23, 2014 (12 years old)
  </ListItem>
  <ListItem>
    Philando Divall Castile, July 6, 2016 (32 years old)
  </ListItem>
  <ListItem>
    Trayvon Benjamin Martin, February 26, 2012 (17 years old)
  </ListItem>
  <ListItem>
    Breonna Taylor, March 13, 2020 (26 years old)
  </ListItem>
  <ListItem>
    Shantel Davis, June 14, 2012 (23 years old)
  </ListItem>
  <ListItem>
    Walter Scott, April 4, 2015 (50 years old)
  </ListItem>
  <ListItem>
    Mario Gonzalez, April 19, 2021 (26 years old)
  </ListItem>
</OrderedList>

Ordered Display List

Use an Ordered Display List when you need a visually enhanced numbered list to improve the scannability of sequential steps, instructions, or other content within a single screen.

Keep the following guidance in mind when using this component:

Choose a font size for list item labels that doesn't exceed the size of higher hierarchy levels on the page.
For elements under the list item, avoid using text with a font size larger than the list item label.
Keep list items labels concise, providing clear and actionable steps for the user to follow.

(warning)

Alignment considerations

If you're not utilizing the OrderedDisplayListHeadingcomponent, please note that only the heading50 andheading60 variants are automatically aligned with their corresponding list item numbers.

<div>
  <Heading variant="heading30" as="h3">Getting started with unified profiles</Heading>
  <OrderedDisplayList variant="heading40">
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Set up your Segment Unify space</OrderedDisplayListHeading>
      <Stack orientation="vertical" spacing="space40">
        <div>To get started, let's set up your Segment Unify space. We'll take you to Segment to do this.</div>
        <Anchor href="https://segment.com" showExternal>
          Continue setup in Segment
        </Anchor>
      </Stack>
    </OrderedDisplayListItem>
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Confirm your identifier settings</OrderedDisplayListHeading>
      <Stack orientation="vertical" spacing="space40">
        <div>Segment uses identifiers to look up customer profiles. Give your identifiers display
        names, and select the identifiers to use for automatic profile search.</div>
        <Anchor href="https://segment.com" showExternal>
          Continue setup in Segment
        </Anchor>
      </Stack>
    </OrderedDisplayListItem>
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Choose your traits</OrderedDisplayListHeading>
      <Stack orientation="vertical" spacing="space40">
        <span>
          Customer profiles on your Segment Unify space may include a large number of traits.
          Choose the traits you want to make available to Flex agents and give them display
          names.
        </span>
        <Anchor href="https://segment.com" showExternal>
          Continue setup in Segment
        </Anchor>
      </Stack>
    </OrderedDisplayListItem>
  </OrderedDisplayList>
</div>

Nesting list items

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

<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>

Ordered Display List nesting

The Ordered Display List is designed to convey hierarchy without influencing deeper levels. If your content requires more than 2 levels, use Headings to establish hierarchy before starting the list.

All elements under a list item should be included inside the list item, ensuring they share the same indentation.

<div>
  <OrderedDisplayList variant="heading30">
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Vivamus sagittiss</OrderedDisplayListHeading>
      <Stack orientation="vertical" spacing="space40">
        <div>Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</div>
        <OrderedDisplayList variant="heading40">
          <OrderedDisplayListItem>
            <OrderedDisplayListHeading as="div">Vivamus sagittiss</OrderedDisplayListHeading>
            Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
          </OrderedDisplayListItem>
          <OrderedDisplayListItem>
            <OrderedDisplayListHeading as="div">Duis mollis</OrderedDisplayListHeading>
            Duis mollis, est non commodo luctus.
          </OrderedDisplayListItem>
        </OrderedDisplayList>
      </Stack>
    </OrderedDisplayListItem>
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Duis mollis</OrderedDisplayListHeading>
      Duis mollis, est non commodo luctus.
    </OrderedDisplayListItem>
    <OrderedDisplayListItem>
      <OrderedDisplayListHeading as="div">Vivamus sagittiss</OrderedDisplayListHeading>
      <Stack orientation="vertical" spacing="space40">
        <div>Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.</div>
        <OrderedDisplayList variant="heading40">
          <OrderedDisplayListItem>
            <OrderedDisplayListHeading as="div">Vivamus sagittiss</OrderedDisplayListHeading>
            Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
          </OrderedDisplayListItem>
          <OrderedDisplayListItem>
            <OrderedDisplayListHeading as="div">Duis mollis</OrderedDisplayListHeading>
            Duis mollis, est non commodo luctus.
          </OrderedDisplayListItem>
        </OrderedDisplayList>
      </Stack>
    </OrderedDisplayListItem>
  </OrderedDisplayList>
</div>

Composition notes

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.

Dos and don'ts

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.