Skip to content
Skip to search
Paste
Paste
UX Platform
Change the site theme
GitHub
information:
The responsive layout is in early preview. Please report any bugs.link takes you to an external page

List

The list component is used to render text as a list of items.

Status
production
Version
2.0.2
Sources
Github
Storybook
Abstract
Import from
@twilio-paste/core/list — or — @twilio-paste/list
Edit this page on GitHub
  • Tamir Rice
  • Philando Castile
  • Trayvon Martin
  • Breonna Taylor
  • Shantel Davis
  • Walter Scott

Guidelines#

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#

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

List is part of the Typography package, which includes Header and Paragraph as well.

Accessibility#

  • List text should meet AA requirements (4.5:1) for color contrast from itself and the background color
  • ListItems should always have an OrderedList or UnorderedList parent component
  • Nested ListItems should be wrapped in their own, new OrderedList or UnorderedList parent component, e.g.
<OrderedList>
  <ListItem>
    Text of the parent list item
    <OrderedList>
      <ListItem>Nested list item</ListItem>
    </OrderedList>
  </ListItem>
</OrderedList>

Examples#

Unordered List#

Use unordered list to display a basic list of items. This is the default variant for List.

  • Tamir Rice
  • Philando Castile
  • Trayvon Martin
  • Breonna Taylor
  • Shantel Davis
  • Walter Scott

Ordered List#

Use ordered list to display a numbered list of items.

  1. Tamir Rice
  2. Philando Casitle
  3. Trayvon Martin
  4. Breonna Taylor
  5. Shantel Davis
  6. Walter Scott

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.

  1. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
    • Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
    • Duis mollis, est non commodo luctus.
  2. Duis mollis, est non commodo luctus.
  • Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
    1. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor.
    2. Duis mollis, est non commodo luctus.
  • Duis mollis, est non commodo luctus.

Composition Notes#

When to Use a OrderedList and UnorderedList#

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

Anatomy#

PropertyDefault tokenModifiable?
font-sizefont-size-30No
line-heightline-height-30No
font-weightfont-weight-normalNo
margin-topnullYes
margin-bottomspace-70Yes
colorcolor-textNo

Usage Guide#

API#

Installation#

yarn add @twilio-paste/list - or - yarn add @twilio-paste/core

Usage#

import {OrderedList, UnorderedList, ListItem} from '@twilio-paste/list';
const Component = () => (
  <UnorderedList>
    <ListItem>Point one</ListItem>
    <ListItem>Point two</ListItem>
    <ListItem>Point three</ListItem>
  </UnorderedList>
);
const Component = () => (
  <OrderedList>
    <ListItem>Point one</ListItem>
    <ListItem>Point two</ListItem>
    <ListItem>Point three</ListItem>
  </OrderedList>
);

Props#

PropTypeDescriptionDefault
children?ReactNodenull
marginTop?ResponsiveValue<keyof ThemeShape['space']>null
marginBottom?ResponsiveValue<keyof ThemeShape['space']>'space70'

Black lives matter.