Props
Usage guidelines
- To present a grouping of simple, related information. For more complex data, use Table.
- To break up related content into easily digestable chunks.
- 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 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.
Accessibility
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.
Subcomponents
List.Item
List.Item Props
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.
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.
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.
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.
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.
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).
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".
Related
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.