List

A list shows a set of similar things people scan, pick from, or open: providers to log in with, menu options, the devices in an area. Every row has the same structure, so the eye can run down the left edge and find what it needs.

Use a list for:

• A set of similar items that people scan, pick from, or open
• Navigation to the next level, with a chevron at the end of each row
• Rows that only show information, like a value or a message

Don't use a list for:

• Actions on one item. Put them in a dropdown.
• Picking one option from a few that need explaining. Use a select box.
• Content that people show and hide. Use an expansion panel.

1. List: the container, with 8px of padding at the top and bottom
2. Row: one item of the list
3. Graphic: optional, an icon, avatar, or control at the start of the row
4. First line: the main text of the row
5. Second line: optional, a short detail below the first line
6. Meta: optional, content at the end, like a chevron or a short value

Start with the text, then add only what helps people recognize a row:

• An icon at the start.
• A second line, for a short detail, like a state or a description.
• Something at the end, like a chevron when the row opens something, or a short value.

A row reserves room at the start for its graphic, in one of these sizes: an icon, an avatar (a round image), a medium or large image, or a control like a checkbox.

A row that does nothing when selected, like a row that only shows a value or a message, can be made non-interactive. It then has no ripple and no keyboard focus.

• Hover and pressed: an interactive row shows a ripple. It is black unless the theme sets another color. The dark theme sets it to a light gray. An activated row uses the primary color for its ripple.
• Focus: one row at a time is in the tab order. Arrow keys move focus between the rows.
• Activated: in a list where a row can be activated, the selected row gets a primary tint at 12% opacity, and its graphic turns to the primary color.
• Disabled: the text turns to the disabled text color, and the row can't be selected.
• Long text: the first line is cut off with an ellipsis when it doesn't fit. The second line is cut off too, unless the row lets it wrap. Then the row grows with it.

See UI text for how to write labels.

One row at a time is in the tab order. Arrow keys move focus between the rows.

A row is at least 48px high, and as wide as the list.

By default, a screen reader gets no list structure: the list and its rows have no role, so it hears the text of the rows. Disabled rows are announced as disabled. The list can get a role and a name in code, see below.

• The list and its rows have no role by default. Set innerRole on the list and itemRoles for the rows, like listbox and option, and innerAriaLabel for the name of the list.
• A disabled row has aria-disabled="true".
• With the role option, a selected row has aria-selected="true".
• A row with noninteractive can't take focus.

• Dropdown: a menu of actions
• Select box: picking one option from a few
• Expansion panel: content that people show and hide

The element is <ha-list>, with <ha-list-item> rows. Both extend the Material Web Components list.

<ha-list>
  <ha-list-item graphic="icon" twoline hasMeta>
    <ha-svg-icon slot="graphic" path="..."></ha-svg-icon>
    Network
    <span slot="secondary">Connected over Wi-Fi</span>
    <ha-svg-icon slot="meta" path="..."></ha-svg-icon>
  </ha-list-item>
</ha-list>

Attribute names are case-insensitive in HTML, so hasMeta and hasmeta are the same.

• activatable: shows the selected row as activated.
• multi: allows selecting more than one row.
• wrapFocus: arrow keys wrap from the last row to the first, and back.
• rootTabbable: makes the list itself focusable, instead of the first row.
• noninteractive: turns off selection and keyboard navigation for the whole list.
• innerRole and innerAriaLabel: the role and the accessible name of the inner list element.
• itemRoles: the role given to every row, like option.

• graphic: reserves room for content in the graphic slot. icon, avatar, medium, large, or control.
• twoline: shows the secondary slot as a second line.
• multiline-secondary: lets the second line wrap, instead of cutting it off.
• hasMeta: shows the meta slot at the end.
• noninteractive: the row can't be selected or focused.
• disabled: disables the row.
• selected and activated: the selection state.
• value: a value that identifies the row.

• Default: the first line of text.
• secondary: the second line, when twoline is set.
• graphic: an icon, avatar, or control at the start, when graphic is set.
• meta: content at the end, when hasMeta is set.

• action on ha-list: a row was activated. detail.index is the index of the row.
• selected on ha-list: the selection changed. detail.index is the selected index, or a set of indexes with multi.
• request-selected on ha-list-item: the row asks to be selected or deselected. detail.selected is the new state, and detail.source says whether it came from an interaction or a property change.

• --mdc-list-side-padding: the padding on both sides of a row. Defaults to 20px.
• --mdc-list-side-padding-left and --mdc-list-side-padding-right: the padding of one side.
• --mdc-list-item-graphic-margin: the space between the graphic and the text.
• --mdc-list-item-meta-display: the display of the meta slot.

Source: src/components/ha-list.ts and src/components/ha-list-item.ts

The new lists are accessible and keyboard friendly from the start. Pick the container by what the list means, then the item by what a row does. They are not part of the live components on this site yet, so there is no demo.

• <ha-list-base>: a plain list, with the role list. The arrow keys move focus between rows, Home and End jump to the first and last enabled row, Page up and Page down move a page, and Enter or Space activates the focused row. Only one row is in the tab order at a time.
• <ha-list-selectable>: a list people pick from, with the role listbox. Its rows are <ha-list-item-option>. Set multi to allow picking more than one.
• <ha-list-nav>: a list of links, wrapped in a <nav> landmark. Its rows are <ha-list-item-button> with an href. Name the landmark with aria-label.

Attributes of the containers:

• wrap-focus: the arrow keys wrap around at the ends.
• virtual-focus: focus stays outside the list, like in the search field of a picker. The list marks the row the keyboard points at with active, and scrolls it into view. The element that has focus moves it with moveActiveItem().
• aria-label: the accessible name.
• multi: on ha-list-selectable only, allows picking more than one option.

Events:

• ha-list-activated: Enter or Space on a focused row. detail has the index and the item.
• ha-list-item-selected and ha-list-item-deselected: on ha-list-selectable, an option was picked or unpicked. detail is the index of the option. Deselected only fires with multi.

Styling: --ha-list-gap sets the space between rows, --ha-list-padding the padding around the list. Both default to 0.

Every item has the same row layout, with these slots and attributes:

• start: the leading part, like an icon or an avatar.
• end: the trailing part, like a value or a chevron.
• headline and supporting-text: the first and second line, as an attribute or a slot.
• content: replaces the whole middle part.
• disabled: dims the row and blocks the pointer.

The items:

• <ha-list-item-base>: a row that only shows information, with the role listitem. Set interactive to put it in the keyboard navigation of the list without an action, like a row people can sort.
• <ha-list-item-button>: a row that does something. It renders a link when it has an href, and a button otherwise. The whole row is the target.
• <ha-list-item-option>: a row people can pick, with the role option and aria-selected. The list owns the selection. With appearance="checkbox" it shows a checkbox, at the start or the end with selection-position. The default appearance, line, highlights the selected row.

Styling of the rows:

• --ha-row-item-min-height: the minimum height of a row. Defaults to 48px.
• --ha-row-item-padding-block, --ha-row-item-padding-inline, and --ha-row-item-gap: the padding of a row, and the space between its parts.
• --ha-list-item-focus-background and --ha-list-item-active-background: the background on keyboard focus, and of the active row.
• --ha-list-item-selected-background: the background of a selected option, with appearance="line".

Source: src/components/list/ and src/components/item/