Anatomy
List
- Header (Optional): Text displayed above the list items. Use it to label the group.
- List Items: The vertical sequence of items within the container.
- Footnote (Optional): Caption displayed below the list items. Use it to provide additional context or explanations for the group.
ListItem
- Leading visual (Optional): Left-aligned slot for icons, avatars, or thumbnails. Can be vertically centered or top-aligned.
- Header: The primary content area. Expands to fill the space between Leading and Trailing. Typically holds a title, subtitle, and supporting metadata such as badges, labels, or secondary text
- Trailing visual (Optional): Right-aligned slot for secondary labels, controls, or disclosure indicators.
- Content (Optional): A full-width area below the main layout for supplementary information such as preview text.
- Divider: A thin separator rendered at the top of each item. Can be inset (starting after the leading slot) or full-width.
Usage Guidelines
When to Use
- Navigation - Present a list of destinations that let the user move between screens or sections of the app, such as a settings menu or a profile screen with grouped options.
- Toggling settings - Turn features or preferences on and off inline using the Toggle variant.
- Data collections - Display a scrollable set of similar items such as contacts, messages, or search results.
- Selection - Present a group of options the user can choose from, either multi-select or single-select.
When Not to Use
- Rich, standalone content - If an item needs multiple tap targets, prominent imagery, or a non-linear layout, use a Card instead. Cards are better suited for content that stands on its own rather than being one item among many.
- Visual, grid-based navigation - When actions or destinations are better represented as a two-dimensional grid, use Tiles instead.
- Feedback and alerts - Lists are not the right container for status messages, warnings, or confirmations. Use a Banner or an inline alert component instead.
Best Practices
Use succinct labels and be intentional with every element in a list item.
Don't overcrowd a list item with too many elements.
Keep items consistent within a list. If one item has a leading icon, give every item in that group one.
Don’t mix list items with different configurations in the same list, such as varying icon sizes as leading visuals.
Use the appropriate variant for your scenario, such as Toggle for turning a setting on or off.
Build a custom list item for a pattern that a variant already covers.
Be intentional about what is tappable. Make either the entire list item tappable or only specific elements within it
Don't nest tappable elements inside a tappable list item.
Group related items using the Contained list style. Add header or footer captions to give context.
Leave items ungrouped when grouping would help users scan or find a specific item.
Use Contained list to provide visual structure and emphasis on a screen. Even a single item should use Contained when it appears alongside other contained groups.
Switch between Contained and Default styles on the same screen. It breaks visual consistency.
Use inset dividers when a leading element is present.
Use inset dividers when the Content slot is in use. The content area is full-width, so the inset will not align.
General Component Behaviors
Tappable Area
The tappable area depends on the variant. For Navigation, Checkbox, Radio, and Button, the entire list item responds to touch. For Toggle, only the switch control itself is tappable.
When composing custom list items, the same rule applies: a list item should either be tappable as a whole, or it should contain individual tappable elements within its slots, but never both.
Divider Alignment
The divider sits at the top of each item. When set to inset, it starts after the leading slot, visually distinguishing the leading content. When set to full, it spans the entire width.
Horizontal Padding
List items have built-in horizontal padding. Account for this when placing a List within a screen layout. In most cases, the List should span the full width of the screen to avoid double padding. When using the Contained style, add page-level padding around the contained group so it sits correctly within the screen margins.
States
Variants
Navigation
Use Navigation when the item should take the user to another screen or section on tap. It supports a title, optional subtitle, optional leading element, and an optional label.
Toggle
Use Toggle when the user needs to turn a setting or feature on or off. The change takes effect immediately. Only the switch itself is tappable.
Checkbox
Use Checkbox for multi-select scenarios where the user can pick one or more options from a group.
Radio
Use Radio for single-select scenarios where the user picks exactly one option from a set of mutually exclusive choices.
Button
Use Button when the item represents a standalone action, such as "Sign Out" or "Change PIN". Supports primary, secondary, and danger types.
Custom
Use the Custom ListItem to compose your own layout using the available slots: Leading, Header, Trailing, and Content. Reach for this when displaying purely presentational content or when no pre-built variant fits your use case. To keep the visual style consistent with other list items, use the provided helper components — Title, Subtitle, and Label — for text content within the slots.
Styles
List
Default
Items appear in a flat, edge-to-edge layout with no outer decoration. Use this for full-screen lists where the items fill the available width
Contained
Items are wrapped in a rounded card. Use multiple Lists with their own headers and footers to create distinct sections on a screen.
Content Guidelines
- Keep titles short and descriptive, ideally a single line. Use sentence case.
- Use subtitles for supplementary detail, not for repeating information already visible elsewhere on the screen.
- Keep labels brief: a date, a status word, or a short value.
-
Write header and footer captions on the List container to provide context for the group (e.g. "Changes will apply after restart"). Keep them to one or two sentences.
For further information, see the Content Styleguide.
Known Gaps
- Accessibility documentation - Screen reader announcements, focus order, and gesture support for each variant have not yet been specified.
- Swipe actions - Swipe-to-delete, swipe-to-archive, and other trailing/leading swipe gestures are not yet supported.
- Drag-to-reorder - Reorderable lists are a common pattern but are not covered by the current component.
- Loading / skeleton state - A placeholder skeleton for list items while data is being fetched has not been defined.