A list item is the content of one row: an optional leading element, a label and an optional trailing element. It is used inside Menu, Overflow menu, List Picker, Drawer link and Filter sections in drawer content.
Every example on this page is the real component, not a picture. The row itself (height, padding, divider, hover, focus) belongs to the container. Figma: List Item Content.
Choose a breakpoint, size, leading element, label, overline, supporting text and trailing element. The list item and its markup update. The item sits in a demo row, as it would in a Menu. Click it to toggle it.
A list item is the content of one row: an optional leading element, a label and an optional trailing element. It is used inside Menu, Overflow menu, List Picker, Drawer link and Filter sections in drawer content.
List Item has two sizes (Large and Small), seven leading elements, seven trailing elements, a regular or bold label, and optional overline and supporting text. The row itself (height, padding, divider, hover and focus) belongs to the container.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a list item. Specifications holds the values: tokens, sizes, states and requirements. Code shows how to add one to a page.
Use a list item to fill a row in a container that already exists. It is not a page element on its own. Use it:
Every row in a list starts with the same kind of element, so the labels line up and the list is easy to scan.
Use the trailing value only for a short number or text. A long label wraps and breaks the rhythm of the list.
A check box, radio or switch that stands alone in a form is eco-checkbox, eco-radio or eco-switch. A list item draws the same look as a row’s content.
Page navigation links are in Links, tabular data is a Docs table, and a long description with actions is a card or a section.
| The user… | Use |
|---|---|
| chooses from a list that opens from a button or a Select | Menu with list items as rows |
| picks a value in a filter or picker row | List item with a check box, radio or swatch |
| sees one fixed label and value | Plain text, or a table (eco-docs-table) |
| reads a long description with actions | Not a list item: use a card or section |
aria-selected) on the row. A standalone item with a control uses role and aria-checked.<input> inside an option row: the leading box is presentational.text-tertiary.body-md (Large) or body-sm (Small), regular or bold. One line.body-sm in text-tertiary below the label, clipped after two lines.The gap between the parts is 8px. The row height comes from the tallest part and the container.
Seven leading elements and seven trailing elements combine freely, with a regular label, a bold label or no label, and optional overline and supporting text. Use the Breakpoint toggle to preview Desktop (769px and up) and Mobile (below 769px). Sizes are under Sizes below.
What comes before the label: nothing, an icon, a check box, a radio button, a color swatch (alone or in a frame) or an image.
What comes after: nothing, an icon, a short value in secondary or tertiary text, or a control (check box, radio, switch). A trailing control is presentational: the item or row carries the state. Click an item to toggle it.
One to three lines: an optional overline above the label (small uppercase, tertiary) and optional supporting text below it (body-sm, tertiary, clipped after two lines). The container row needs vertical padding for rows taller than one line.
Regular is the default. Bold marks a heading-like row, often with a secondary value.
Large is the default. Small is for compact surfaces. The Large label changes at 769px; Small is the same on every breakpoint. The values are under Sizes in Specifications.
The leading element and the label stay together at the left. The trailing element sits at the far right. All parts are centered vertically, also in rows with an overline or supporting text.
A list item is placed inside a container row. The container draws the row height, the padding, the divider, the hover and the focus.
The item fills the width of its row (width: 100%).
The label is text-primary and trailing text is secondary or tertiary. A selected check box, radio or swatch frame looks like the matching ECO component. Token names and values are under Design Tokens in Specifications.
A list item has no hover or focus of its own: the container row draws them (see Menu). A standalone item with a role gets a pointer and a 2px focus ring.
Inside a container the row carries aria-selected. A standalone item with a check box, radio or switch is itself role="checkbox", "radio" or "switch" with aria-checked: a click, Space or Enter toggles it. A radio only selects, and Arrow keys move inside its radiogroup.
A disabled item has text-disabled text and icons and is not focusable. All states are listed under States in Specifications.
All requirements are listed under Accessibility Requirements in Specifications.
A standalone item is one tab stop. Space or Enter toggles it. In a radio group the checked radio is the tab stop, and the Arrow keys move and select. Inside a Menu the container handles the keys.
The check box, radio and switch parts are aria-hidden. The state comes from aria-selected on the row or aria-checked on a standalone item with a role. Never put a real <input> inside an option row.