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

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







Component props
<React.Element<typeof List.Item>>

Use List.Item to build lists. See subcomponents.

string | React.Element<typeof Text>

The label for the list. Be sure to localize the text. See the label variant for guidance.

"visible" | "hidden"

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.

"regular" | "condensed"

The spacing used in List. See the spacing variant for guidance.

"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

Best practices


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


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


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


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



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.



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
string | React.Element<typeof Text>

The content of the list item. See the text variant for guidance.

<React.Element<typeof List | typeof List.Item>>

Use List.Item to build nested lists. Use List to combine different types nested lists. See subcomponents.



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.


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.


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.

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.

Default label with strings
Custom label with Text
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.


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

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

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

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