Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

List

Version 8.2.0GithubStorybook

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:

  • 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

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

Ordered Display List vs Progress Steps page anchor

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

Accessibility page anchor
  • 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

Examples page anchor

Unordered List

Unordered List page anchor

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

Ordered List page anchor

Use ordered list to display a numbered list of items.

Component preview theme
<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

Ordered Display List page anchor

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.

Component preview theme
<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

Nesting list items page anchor

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>

Ordered Display List nesting

Ordered Display List nesting page anchor

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.

Component preview theme
<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

Composition notes page anchor

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

Dos and don'ts page anchor
  • 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.