Unordered List element

Lists are vertical groupings of related content. List items begin with either a number or a bullet.

When to use

Use lists when you need to group content together.
Use bulleted lists when you don’t need to convey a specific order for list items.
Use numbered lists when you need to convey a priority, hierarchy, or sequence between list items.

Alternatives and related components

- Use cards if more than three lines of text need to be shown in list tiles
- Use tables for more complex sets of data

Anatomy

The list consists of:

- Marker: a dot or a number in front of the list item
- Label: the name of the list item

Design properties

Typography

- Label: TheSans/md/400

Colors

- Marker: Grey/4
- Label: text color Grey/4

Structure

- Marker: dot size 5px, padding-right 8px
- Label: padding-left 8px
- Nested list item: padding-left 16px
- Nested label: padding-left 8px

Accessibility

[technical accessibility requirements]

List variants

Unordered lists
To present content of equal status or value.

Ordered lists
Imply sequence and order, and are commonly used when giving a set of instructions.

Content guidelines

List items
Every item in a list should:

- Start with a capital letter
- Not use commas or semicolons at the end of each line
- Be written in sentence case

Length
Generally, lists should be used to present simple pieces of information. For more complex sets of data, consider using a data table.

Order
Arrange list items in a logical way. For example, if the list is about resource use, the default order might be highest resource use to lowest. Grouping items in categories into smaller, more specific lists might be more meaningful in some contexts.

Text
Use list items that are grammatically parallel. For example, do not mix passive voice with active voice or declarative sentences (statements) with imperative sentences (direct command).

Best practices

$3

Lists should:

- Break up chunks of related content to make the information easier for merchants to scan
- Be phrased consistently (try to start each item with a noun or a verb and be consistent with each item)

$3

Lists should:

- Not be used for lists where the entire item represents an action

References

- https://www.carbondesignsystem.com/components/list/usage
- https://polaris.shopify.com/components/lists-and-tables/list#navigation