List

Anatomy

1. List: A collection of similar items
2. List Item: Rows within the list
3. Lead Content (Optional): Visual elements such Avatars or Icons placed at the start of the row
4. Label(s): Up to three labels that help identify the item. The first line is mandatory, the other two are optional. The 2nd and 3rd line may be used to show attributes or body text.
5. Trailing Content (Optional): Secondary controls or metadata placed at the end.

Usage Guidance

A List is a flexible container that holds related options. ListItems are options represented as rows in the List. Note: Only ListItem is represented as a UI Component. To create a list in iOS, developers will create a set of repeated ListItems into a single column.

Lists are used to help users scan and select from multiple options. They have many applications, such as forms, navigation, and actions. Lists are core building blocks for other components, such as Menus.

When to Use

• When users need to compare options against each other to make a selection.
• When all entries are related and of the same type.
• When its useful to see many entries in context to each other.
• Users are browsing and may not know what they are looking for.
• Entries are dynamic, constantly changing.

When Not to Use

• Use a Card if you need more space to convey the message, or if visual impact is a priority.
• Use a Grid if you need to show more details about a topic than can fit in a ListItem, or to display more entries in the viewport at once.

Repeatable

ListItem in the same list should share content structure. Avoid mixing ListItem styling and content. Having a repeatable structure makes Lists easier to scan.

Scannable

Lists should be easy to scan. Keep content aligned to keylines, creating a familiar scanning path. Aligning to an edge helps guide the eye when looking for the start of the next item.

Be mindful of the List Item content. Decorative imagery or overly wordy labels will slow down users.

• Keep content directly related to the topic.
• Keep labels concise, only adding what’s necessary.
• Primary content should be placed at the start, and supplemental information at the end.

Flexible

List Items are built to be highly flexible to support a variety of user needs.

Before building a List, plan out a content structure based off the most important details to show.

Here are some examples of custom lists:

Course list example

Settings example

List card example

Touch Targets

ListItem is interactive and should take users to more details.

1. Primary actions are placed on entire surface area of the list item.
2. Secondary actions are placed at the end of the row and may have their own touch target. Use a minimum touch area of 48 on trailing controls

For more than two actions, place them in an overflow Menu.

Behaviors

States

State is used to facilitate interaction and provide feedback:

State	Description	Example
Inactive	Element is interactive
Pressed	Element is being pressed
Disabled	Non-interactive
Selected	Element is selected

Selection

Selection controls are placed at the start of the row, before content.

• Use a Radio for single-select lists.
• Use a Checkbox for multi-select lists.

If a list item has a leading Radio or Checkbox, they will not have the option to display a trailing item. Using these controls implies that the primary user action is selection - the whole row is interactive.

Navigation

To indicate navigation within a folder or tree structure, use a right chevron system icon at the end of the row. These navigate users a level deeper in the structure.

Loading

Skeletons are used as placeholders for content if the List takes more than a second. Showing the general shape of the List with placeholder loaders improves perceived performance by reducing the time for meaningful content to show.

Virtualized Lists

High volume lists load items visible in the viewport upfront. As users scroll, items within are loaded to reduce the chance of users running into loading items.

Lists vs Card

While both are entry points to a topic, ListItems are generally less variable than Cards. ListItems share size, spacing, and general layout rules.

Use a Card instead of Lists if:

• More space is needed to get a point across.
• Content between entries may be variable.
• Visual presentation is a higher priority than showing more entries at once.

Lists vs Tables

Similar to Lists, Tables show related entries in context to each other for comparison. However, Grids are more dense. Use a Grid if:

• You need to show more entries at once.
• You need to show more details or attributes about each entry.

Examples

Labels

ListItem can have 1, 2, or 3 lines of text. Lines represent a new row within the body of the List Item. The first line serves as the identifying label and is the only mandatory element of the List Item. The 2nd and 3rd line can be used for attributes and body text.

Size

ListItem come in 4 sizes: x-small, small, medium, and large.

Use x-small for denser action lists. The small size is the default. If more space is required, medium and large sizes may be used.

Increases in size only increase the height of ListItem, with no impact to width.

No Padding

Padding may be removed if ListItem needs to be used within a container that defines its own padding.

Lead Visuals

Leading visuals are optional and appear at the start of the row. Visuals are non-decorative and should be used to inform content type or status of the ListItem.

Trailing Controls

May be used for secondary actions with a standalone touch target, such as opening a related actions Menu.

Trailing Metadata

Used to display secondary information about the ListItem. For example, showing a status, count, or hint text that implies the interaction to follow.

Selectable

When used in forms, selection controls are placed at the start of the row. These indicators do not have a standalone touch target. Instead, selection is considered a primary action — tapping the row selects the item.

Standalone

ListItem is rounded by default, meaning they use a mobile friendly inset styling that is visible when pressed or selected. This inset styling may be disabled if ListItem is used as a standalone element, such as within a Card.

Truncation

Shown below are the default truncation and line-limit rules for List Items.

These rules may be overridden by feature teams as needed. Try to avoid truncating text if there isn’t a way for the user to see the full string.

In general, keep content short and to the point. Large amounts of text in Lists are usually unnecessary - consider alternate ways to reduce content.

API Guidelines

Coming soon…

Accessibility Guidelines

Coming soon…

Content Guidelines

Coming soon…

Anatomy

1. List: A collection of similar items
2. List Item: Rows within the list
3. Lead Content (Optional): Visual elements such Avatars or Icons placed at the start of the row
4. Label(s): Up to three labels that help identify the item. The first line is mandatory, the other two are optional. The 2nd and 3rd line may be used to show attributes or body text.
5. Trailing Content (Optional): Secondary controls or metadata placed at the end.

Usage Guidance

A List is a flexible container that holds related options. ListItems are options represented as rows in the List. Note: Only ListItem is represented as a UI Component. To create a list in Android, developers will create a set of repeated ListItems into a single column.

Lists are used to help users scan and select from multiple options. They have many applications, such as forms, navigation, and actions. Lists are core building blocks for other components, such as Menus.

When to Use

• When users need to compare options against each other to make a selection.
• When all entries are related and of the same type.
• When its useful to see many entries in context to each other.
• Users are browsing and may not know what they are looking for.
• Entries are dynamic, constantly changing.

When Not to Use

• Use a Card if you need more space to convey the message, or if visual impact is a priority.
• Use a Grid if you need to show more details about a topic than can fit in a ListItem, or to display more entries in the viewport at once.

Repeatable

ListItems in the same list should share content structure. Avoid mixing ListItem styling and content. Having a repeatable structure makes Lists easier to scan.

Scannable

Lists should be easy to scan. Keep content aligned to keylines, creating a familiar scanning path. Aligning to an edge helps guide the eye when looking for the start of the next item.

Be mindful of the List Item content. Decorative imagery or overly wordy labels will slow down users.

• Keep content directly related to the topic.
• Keep labels concise, only adding what`s necessary.
• Primary content should be placed at the start, and supplemental information at the end.

Flexible

List Items are built to be highly flexible to support a variety of user needs.

Before building a List, plan out a content structure based off the most important details to show.

Here are some examples of customized lists:

Course list example

Settings example

List card example

Touch Targets

ListItem is interactive and should take users to more details.

1. Primary actions are placed on entire surface area of the list item.
2. Secondary actions are placed at the end of the row and may have their own touch target. Use a minimum touch area of 48 on trailing controls

For more than two actions, place them in an overflow Menu.

Behaviors

States

State is used to facilitate interaction and provide feedback:

State	Description	Example
Inactive	Element is interactive
Pressed	Element is being pressed
Disabled	Non-interactive
Selected	Element is selected

Selection

Selection controls are placed at the start of the row, before content.

• Use a Radio for single-select lists.
• Use a Checkbox for multi-select lists.

If a list item has a leading Radio or Checkbox, they will not have the option to display a trailing item. Using these controls implies that the primary user action is selection - the whole row is interactive.

Navigation

To indicate navigation within a folder or tree structure, use a right chevron system icon at the end of the row. These navigate users a level deeper.

Loading

Skeletons are used as placeholders for content if the List takes more than a second. Showing the general shape of the List with placeholder loaders improves perceived performance by reducing the time for meaningful content to show.

Virtualized Lists

High volume lists load items visible in the viewport upfront. As users scroll, items within are loaded to reduce the chance of users running into loading items.

Selection

Selection controls are placed at the start of the List Item, before any text or media elements.

• Use a Radio for single-select lists.
• Use a Checkbox for multi-select lists.

If a list item has a leading Radio or Checkbox, they will not have the option to display a trailing item. Using these controls implies that the primary user action is selection, and the whole row will become tappable.

Navigation

To indicate navigation within a folder or tree, a rightward chevron should be placed at the end of the row. These take users a level deeper in the data structure.

Loading

Skeletons are used as placeholders for List content if it takes more than 1 second to load. Showing the general shape of the List through Skeletons improves perceived performance by reducing the time it takes for meaningful content to populate the screen.

Virtualized Lists

High volume lists load items visible in the viewport upfront. As users scroll, items below get loaded in chunks to reduce the likelihood of users running into items that are still loading.

When to Use

Lists provide entry points to more details about a topic. Use Lists:

• To compare options against each other for selection
• Entries are related and of the same type.
• It’s useful to see many entries in context to each other.
• Users are browsing and may not know what they are looking for.
• Entries are dynamic, constantly changing.

When Not to Use

• Use a Card if you need more space to convey the message, or if visual impact is a priority.
• Use a Grid if you need to show more details about a topic than can fit in a ListItem, or to display more entries in the viewport at once.

Lists vs Card

While both are entry points to a topic, List Items are generally less variable than Cards. ListItems share size, spacing, and general layout rules. Use a Card instead of Lists if:

• More space is needed to get the point across.
• Content between entries is variable.
• Visual presentation is more of a priority rather than showing entries next to each other.

Lists vs Grids

Similar to Lists, Grids show related entries in context to each other for comparison. However, Grids are more dense. Use a Grid if:

• You need to show more entries at once.
• You need to show more details or attributes about each entry.

Examples

Labels

ListItem can have 1, 2, or 3 lines of text. Lines represent a new row within the body of the List Item. The first line serves as the identifying label and is the only mandatory element of the List Item. The 2nd and 3rd line can be used for attributes and body text.

Size

ListItem come in 4 sizes: x-small, small, medium, and large.

Use x-small for denser action lists. The small size is the default, and is suitable for most lists. If more space is required for actions like local navigation, medium and large sizes should be used. Increases in size only increase the height of ListItem - width is not impacted.

No Padding

Padding may be removed if ListItem needs to be used within a container that defines its own padding.

Lead Visuals

Leading visuals are optional and appear at the start of an item. They’re used to inform the content type and status of the List Item.

Trailing Controls

Can be used to indicate a secondary interaction with a standalone touch target, such as opening a related actions Menu.

Trailing Metadata

For secondary information that provide more details about the entry. Place metadata at the end of the item for things like status, numeric counts, or hint text.

Selectable

When used in forms, place selection controls at the beginning of the row. These should not have a standalone touch target as selection is considered a primary action. Tapping the entire row will select the option.

Standalone

ListItem is rounded by default, meaning they use a mobile friendly inset styling that is visible when pressed or selected. This inset styling may be disabled if used as a standalone element, such as within a Card.

Truncation

Shown below are the default truncation and line-limit rules for List Items.

These rules may be overridden by feature teams if needed. Try to avoid truncating text if there is no way for the user to see the full string when interacting with ListItem.

In general, aim to keep content short and to the point. Large bodies of text in Lists usually are not necessary. Consider ways to reduce content or consider using something else.

API Guidelines

Coming soon…

Accessibility Guidelines

Coming soon…

Content Guidelines

Coming soon…