List
Pilot

List allows users to view individual, but related, text items grouped together.

also known as Unordered List, Ordered list, <ol>, <ul>, <li>

Figma:

N/A

Web:

iOS:

Android:

A11y:

This application will be able to

Access your follows and followers
Create new Pins for you
Follow things for you

<List label="This application will be able to" type="unordered">
  <List.Item text="Access your follows and followers"/>
  <List.Item text="Create new Pins for you" />
  <List.Item text="Follow things for you" />
</List>

<List label="This application will be able to" type="unordered">
  <List.Item text="Access your follows and followers"/>
  <List.Item text="Create new Pins for you" />
  <List.Item text="Follow things for you" />
</List>

Props

Component props
Name	Type	Default
`children` Required	`<React.Element<typeof List.Item>>`	-
	Use List.Item to build lists. See subcomponents.
`label`	`string \| React.Element<typeof Text>`	-
	The label for the list. Be sure to localize the text. See the label variant for guidance.
`labelDisplay`	`"visible" \| "hidden"`	`"visible"`
	Whether the label should be visible or not. If `hidden`, the label is still available for screen reader users, but does not appear visually. See the accessibility section and the label variant for guidance.
`spacing`	`"regular" \| "condensed"`	`"regular"`
	The spacing used in List. See the spacing variant for guidance.
`type`	`"bare" \| "ordered" \| "unordered"`	-
	Determines the style of the list. See the type variant to learn more.

Usage guidelines

When to use

To present a grouping of simple, related information. For more complex data, use Table.
To break up related content into easily digestable chunks.

When not to use

When whole list items are navigational. Use a navigational component like Tabs or SideNavigation instead.
When list items require interaction. Use RadioGroup or CheckBox with FieldSet instead.

Best practices

Use the synchronous analytics endpoints if:

You need data from the last 90 days
You want a quick response to load a user facing dashboard/component in real time
You want to avoid large report size/unnecessary data being returned
You need only basic key metrics for each campaign/ad/etc

Use List when you are displaying more than two items or points.

August 15, 2022

Shopping

Added new catalog endpoint to list filtered products.

Don't

Use List if you are displaying fewer than two items. Instead, consider how to present the information as plain text on the page.

With bulk actions, you can:

Request an asynchronous bulk report on advertiser entities campaigns, ad groups, product groups, ads, keywords. Learn more
Create/update ad-related entities

Include links if they are relevent to better understanding the context of the list.

Need more help?

Visit our Help Center
Request a demo

Don't

Use List if the whole list item is selectable. Instead use a navigational component or FieldSet.

Accessibility

Ready

Labels

List comes with a label built-in: just use the label prop.

We recommend using a label prop in all lists. The label will be announced by the screenreader describing the purpose or contents of the list. Even though text preceding the list can introduce the list, screenreaders will read both pieces of information in sequential order. When using the label prop, the information is embedded into the list announcement supporting the comprehension of the list.

However, if List is labeled by content elsewhere on the page or a more descriptive label is needed, the labelDisplay prop can be set to 'hidden'. In this case, it is still available to screen reader users, but will not appear visually on the screen.

The following examples showcase different cases where labels need to be hidden.

Asynchronous Analytics Endpoints

Use the synchronous analytics endpoints if:

You need data from the last 90 days
You want a quick response to load a user facing dashboard/component in real time
You want to avoid large report size/unnecessary data being returned
You need only basic key metrics for each campaign/ad/etc

<Flex gap={4} direction="column">
  <Heading accessibilityLevel="none" size="500">Asynchronous Analytics Endpoints</Heading>
  <List labelDisplay="hidden" label="Use the synchronous analytics endpoints if:" type="unordered">
    <List.Item text="You need data from the last 90 days" />
    <List.Item text="You want a quick response to load a user facing dashboard/component in real time" />
    <List.Item text="You want to avoid large report size/unnecessary data being returned" />
    <List.Item text="You need only basic key metrics for each campaign/ad/etc" />
  </List>
</Flex>

<Flex gap={4} direction="column">
  <Heading accessibilityLevel="none" size="500">Asynchronous Analytics Endpoints</Heading>
  <List labelDisplay="hidden" label="Use the synchronous analytics endpoints if:" type="unordered">
    <List.Item text="You need data from the last 90 days" />
    <List.Item text="You want a quick response to load a user facing dashboard/component in real time" />
    <List.Item text="You want to avoid large report size/unnecessary data being returned" />
    <List.Item text="You need only basic key metrics for each campaign/ad/etc" />
  </List>
</Flex>

The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.

Best practices for Save Button for developers

Pin type settings: Include 'pinit.js' correctly
Use the Save button that’s best for your website
Multiple images on a page (like a blog)

<Flex gap={4} direction="column">
  <Text>The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.</Text>
  <List labelDisplay="hidden" label="Best practices for Save Button for developers" type="unordered">
    <List.Item text="Pin type settings: Include 'pinit.js' correctly" />
    <List.Item text="Use the Save button that’s best for your website" />
    <List.Item text="Multiple images on a page (like a blog)" />
  </List>
</Flex>

<Flex gap={4} direction="column">
  <Text>The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.</Text>
  <List labelDisplay="hidden" label="Best practices for Save Button for developers" type="unordered">
    <List.Item text="Pin type settings: Include 'pinit.js' correctly" />
    <List.Item text="Use the Save button that’s best for your website" />
    <List.Item text="Multiple images on a page (like a blog)" />
  </List>
</Flex>

Subcomponents

List.Item

List.Item is a subcomponent of List. List.Item represents the <li> tag nested within a <ul> or <ol> list tag.

Lists that don't require a alternating between "ordered", "unordered" or "base" can just nest List.Item into each other to build nested lists. If type alternation is required, use List

List.Item Props

List.Item subcomponent props
Name	Type	Default
`text` Required	`string \| React.Element<typeof Text>`	-
	The content of the list item. See the text variant for guidance.
`children`	`<React.Element<typeof List \| typeof List.Item>>`	-
	Use List.Item to build nested lists. Use List to combine different types nested lists. See subcomponents.

Variants

Type

1. Bare: An unordered list without any bullets or alphanumeric sequence.
2. Unordered: An unordered list that does not have a sequential order. List items include a bullet point.
3. Ordered: An ordered list that contains items in a sequential order or priority. List items follow an alphanumeric sequence.

Bare list

List item text
List item text
List item text
List item text

<List label={<Text weight="bold">Bare list</Text>} type="bare">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

<List label={<Text weight="bold">Bare list</Text>} type="bare">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

Unordered list

List item text
List item text
List item text
List item text

<List label={<Text weight="bold">Unordered list</Text>} type="unordered">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

<List label={<Text weight="bold">Unordered list</Text>} type="unordered">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

Ordered list

List item text
List item text
List item text
List item text

<List label={<Text weight="bold">Ordered list</Text>} type="ordered">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

<List label={<Text weight="bold">Ordered list</Text>} type="ordered">
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
  <List.Item text="List item text" />
</List>

Spacing

1. Default: Space between lines defaults at 16px.
2. Condensed: Space between lines is reduced for all style varients to 8px for more condensed screens.

Regular spacing

List item text
List item text
- List item text
  - List item text
  - List item text
  - List item text
- List item text
- List item text
List item text

<List label={<Text weight="bold">Regular spacing</Text>} type="unordered" spacing="regular">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List.Item text="List item text">
        <List.Item text="List item text" />
        <List.Item text="List item text" />
        <List.Item text="List item text" />
    </List.Item>
    <List.Item text="List item text" />
    <List.Item text="List item text" />
  </List.Item>
  <List.Item text="List item text" />
</List>

<List label={<Text weight="bold">Regular spacing</Text>} type="unordered" spacing="regular">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List.Item text="List item text">
        <List.Item text="List item text" />
        <List.Item text="List item text" />
        <List.Item text="List item text" />
    </List.Item>
    <List.Item text="List item text" />
    <List.Item text="List item text" />
  </List.Item>
  <List.Item text="List item text" />
</List>

Condensed spacing

List item text
List item text
- List item text
  - List item text
  - List item text
  - List item text
- List item text
- List item text
List item text

<List label={<Text weight="bold">Condensed spacing</Text>} type="unordered" spacing="condensed">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List.Item text="List item text">
        <List.Item text="List item text" />
        <List.Item text="List item text" />
        <List.Item text="List item text" />
    </List.Item>
    <List.Item text="List item text" />
    <List.Item text="List item text" />
  </List.Item>
  <List.Item text="List item text" />
</List>

<List label={<Text weight="bold">Condensed spacing</Text>} type="unordered" spacing="condensed">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List.Item text="List item text">
        <List.Item text="List item text" />
        <List.Item text="List item text" />
        <List.Item text="List item text" />
    </List.Item>
    <List.Item text="List item text" />
    <List.Item text="List item text" />
  </List.Item>
  <List.Item text="List item text" />
</List>

Nesting

List allows a maximum of six nested list items levels. Unordered lists alternate between a filled and hollow dots. Ordered lists alternate a sequence of numbers, uppercase letters, and lowercase letters.

List.Items can be nested into each other to created nested levels. Choosing to explicitly set List on each new nested level has the same effect. Gestalt List makes sure to build the right <ul>/<ol> > <li> structure under the hood in both cases. Ommiting nested Lists reduces the amount of (nested) code improving readability and faster development.

Unordered and ordered lists can be combined in the same list as well. However, to combine them, we must explicitly set List in the level with the new type.

Bare unordered nested

List item text
- List item text
  - List item text
    - List item text
      - List item text
        List item text

<List label={<Text weight="bold">Bare unordered nested</Text>} type="bare">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

<List label={<Text weight="bold">Bare unordered nested</Text>} type="bare">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

Unordered nested

List item text
- List item text
  - List item text
    - List item text
      - List item text
        List item text

<List label={<Text weight="bold">Unordered nested</Text>} type="unordered">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

<List label={<Text weight="bold">Unordered nested</Text>} type="unordered">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

Ordered nested

List item text
1. List item text
  1. List item text
    1. List item text
      1. List item text
        List item text

<List label={<Text weight="bold">Ordered nested</Text>} type="ordered">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

<List label={<Text weight="bold">Ordered nested</Text>} type="ordered">
  <List.Item text="List item text">
    <List.Item text="List item text">
      <List.Item text="List item text">
        <List.Item text="List item text">
          <List.Item text="List item text">
            <List.Item text="List item text" />
          </List.Item>
        </List.Item>
      </List.Item>
    </List.Item>
  </List.Item>
</List>

Mixed nested

List item text
List item text
- List item text
- List item text
  - List item text
  - List item text
    1. List item text
    2. List item text
- List item text
List item text

<List spacing="condensed" label={<Text weight="bold">Mixed nested</Text>} type="ordered">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List type="unordered">
      <List.Item text="List item text"/>
      <List.Item text="List item text">
          <List.Item text="List item text" />
          <List.Item text="List item text">
            <List type="ordered">
              <List.Item text="List item text" />
              <List.Item text="List item text" />
            </List>
          </List.Item>
      </List.Item>
      <List.Item text="List item text" />
    </List>
  </List.Item>
  <List.Item text="List item text" />
</List>

<List spacing="condensed" label={<Text weight="bold">Mixed nested</Text>} type="ordered">
  <List.Item text="List item text" />
  <List.Item text="List item text">
    <List type="unordered">
      <List.Item text="List item text"/>
      <List.Item text="List item text">
          <List.Item text="List item text" />
          <List.Item text="List item text">
            <List type="ordered">
              <List.Item text="List item text" />
              <List.Item text="List item text" />
            </List>
          </List.Item>
      </List.Item>
      <List.Item text="List item text" />
    </List>
  </List.Item>
  <List.Item text="List item text" />
</List>

Text and label

List's label prop and ListItem's text prop accept either a string or Text. Use a string when no visual style is needed. List will handle the text style and adherence to design guidelines.

If custom styles are required, such as bold text, a different size, or inline links, use Text to wrap the content with any additional Text or Link components as needed. If using a Text component, do not specify color. Toast will automatically pick the correct text color for the given variant.

List's label prop is used for accessibility purposes. See the accessibility guidelines section for more information.

Button settings

Pin type settings: Pin type settings control what content Pinners can save from your page
Button style settings: Button style settings control how your button looks
Source settings: Source settings control canonical sources, including descriptions, urls and images

<List label="Button settings" type="unordered">
  <List.Item text="Pin type settings: Pin type settings control what content Pinners can save from your page" />
  <List.Item text="Button style settings: Button style settings control how your button looks" />
  <List.Item text="Source settings: Source settings control canonical sources, including descriptions, urls and images" />
</List>

<List label="Button settings" type="unordered">
  <List.Item text="Pin type settings: Pin type settings control what content Pinners can save from your page" />
  <List.Item text="Button style settings: Button style settings control how your button looks" />
  <List.Item text="Source settings: Source settings control canonical sources, including descriptions, urls and images" />
</List>

Default label with strings

Button settings

Pin type settings: Pin type settings control what content Pinners can save from your page
Button style settings: Button style settings control how your button looks
Source settings: Source settings control canonical sources, including descriptions, urls and images

<List label={<Text size="400" weight="bold">Button settings</Text>} type="unordered">
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Pin type settings: </Text>
      Pin type settings control what content Pinners can save from your page
    </Text>}
  />
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Button style settings: </Text>
      Button style settings control how your button looks
    </Text>}
  />
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Source settings: </Text>
      Source settings control canonical sources, including descriptions, urls and images
    </Text>}
  />
</List>

<List label={<Text size="400" weight="bold">Button settings</Text>} type="unordered">
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Pin type settings: </Text>
      Pin type settings control what content Pinners can save from your page
    </Text>}
  />
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Button style settings: </Text>
      Button style settings control how your button looks
    </Text>}
  />
  <List.Item text={
    <Text inline>
      <Text weight="bold" inline>Source settings: </Text>
      Source settings control canonical sources, including descriptions, urls and images
    </Text>}
  />
</List>

Custom label with Text

The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.

Best practices for Save Button for developers

Pin type settings: Include 'pinit.js' correctly
Use the Save button that’s best for your website
Multiple images on a page (like a blog)

<Flex direction="column" gap={4}>
  <Text>The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.</Text>
  <List labelDisplay="hidden" label="Best practices for Save Button for developers" type="unordered">
    <List.Item text="Pin type settings: Include 'pinit.js' correctly" />
    <List.Item text="Use the Save button that’s best for your website" />
    <List.Item text="Multiple images on a page (like a blog)" />
  </List>
</Flex>

<Flex direction="column" gap={4}>
  <Text>The Save button is one of the best ways to get your content onto Pinterest —through visitors to your site. Make sure your Save button is doing the most for you by following our best practices.</Text>
  <List labelDisplay="hidden" label="Best practices for Save Button for developers" type="unordered">
    <List.Item text="Pin type settings: Include 'pinit.js' correctly" />
    <List.Item text="Use the Save button that’s best for your website" />
    <List.Item text="Multiple images on a page (like a blog)" />
  </List>
</Flex>

Hidden label

Subcomponent composability

List requires its own subcomponents as children to build the list.

When building List, we might want to render different combinations of subcomponents conditionally. List supports simple conditional rendering of subcomponents lists wrapped in React.Fragment as well as consecutive arrays of subcomponent arrays. See the example below which illustrates both of these cases.

List with conditionals

List item text z
List item text 0
- List item text 1
- List item text 2
- List item text 3
List item text A
List item text B

function Example() {
  const someCondition = true;

  return (
    <List label="List with conditionals" type="unordered">
      { someCondition && <List.Item text="List item text z" /> }
      <List.Item text="List item text 0">
        { someCondition
          && <React.Fragment>
              <List.Item text="List item text 1" />
              <List.Item text="List item text 2" />
              <List.Item text="List item text 3" />
            </React.Fragment>
          }
      </List.Item>
      { someCondition
        && <React.Fragment>
            <List.Item text="List item text A" />
            <List.Item text="List item text B" />
          </React.Fragment>
      }
    </List>
  )
}

function Example() {
  const someCondition = true;

  return (
    <List label="List with conditionals" type="unordered">
      { someCondition && <List.Item text="List item text z" /> }
      <List.Item text="List item text 0">
        { someCondition
          && <React.Fragment>
              <List.Item text="List item text 1" />
              <List.Item text="List item text 2" />
              <List.Item text="List item text 3" />
            </React.Fragment>
          }
      </List.Item>
      { someCondition
        && <React.Fragment>
            <List.Item text="List item text A" />
            <List.Item text="List item text B" />
          </React.Fragment>
      }
    </List>
  )
}

Writing

Length. Content should be short and to the point. Text can be sentence fragments. If you are looking to present more complex information, use Table instead.
Formatting. Text should be in sentence case, with a capital letter at the beginning of the phrase.
Phrasing. Phrase items in a similar way. For example, use a verb for the first word in each sentence (Download, Get, Book).

Don't

Puctuation. For short phrases, do not use periods, commas, semicolons, or any sort of punctuation at the end of each line. If the content is longer than two sentences, add a period at the end of all sentences.
Phrasing. Avoid repeating the first word in each list item. Instead of "Take a nap, Take a hike, Take a lap", try something like "Lie down for a nap, Go on a hike, Run a lap".

Text
The Text component is for all non-heading text on all surfaces.

Table
Table is a set of structured data that is easy for users to scan, examine and compare.

Fieldset
Fieldset creates a fieldset and legend for a group of related form items, like RadioGroup or CheckBox.

Edit page on GitHub

; Opens a new tab

List Pilot

also known as Unordered List, Ordered list, <ol>, <ul>, <li>

Props

Usage guidelines

Best practices

Accessibility

Labels

Subcomponents

List.Item

List.Item Props

Variants

Type

Spacing

Nesting

Text and label

Subcomponent composability

Writing

Related

List
Pilot