List Item

When to use

Use the List Item component to present related content in a structured, scannable list. Select the appropriate variant based on the interaction model.

Use a List Item when:

• You need to display related content in a structured list
• The row acts as a non-interactive container
• You need to include independent interactive elements in leading or trailing slots
• You want to support components such as toggles, switches, badges, or menus within a row
• You need consistent layout for scanning and comparison of items

Use a Navigation List Item when:

• The entire row performs a single action
• The interaction navigates to another view or opens details
• You need a clear, tappable list row for drill-down behavior
• The row should communicate forward navigation with a trailing chevron
• The content supports hierarchical browsing or step-by-step flows

When not to use

Do not use a List Item when:

• The entire row behaves as a single navigation or action target. Use Navigation List Item instead.
• The content is not part of a structured list
• You need a single standalone action. Use Button instead.
• You need grouped or richer content layouts outside of a list context. Use Card instead.

Do not use a Navigation List Item when:

• The row contains independent interactive elements. Use List Item instead.
• The interaction does not navigate or drill down into another view
• Multiple actions exist within the same row
• The row acts as a container for controls such as toggles, switches, or menus
• You need more complex grouping or layout structure. Use Card instead.

Spacing and layout

Layout rules

• Align all content to a shared vertical grid across list items
• Vertically align leading and trailing elements with the content area
• Keep the content area as the primary visual focus
• Reserve space for the trailing chevron in Navigation List Items to maintain consistent alignment

Container spacing

• Use consistent vertical spacing between List Items to support scanning and grouping
• Maintain the same spacing between items within a given context

Responsive behavior

• Allow content to wrap on smaller screens without disrupting the alignment of leading or trailing slots
• Keep the trailing chevron fixed in Navigation List Items. Do not let it wrap or reposition.
• Maintain consistent touch target sizes across breakpoints to support reliable mobile interaction