# Lists Lists are continuous, vertical indexes of text and images, with optional selection, reordering, expanding and swipe actions. **Example: A segmented list of three items with supporting and trailing text** ```html celebration Festivals Food, music, arts, community May 8 palette Arts Literature, games, music May 12 groups Family and friends The relationships that bring and bind May 20 ``` ## Usage guidelines * **Make items easy to scan.** Keep labels short, order items in a logical way such as alphabetical or numerical, and show icons, text and actions in a consistent format. * **Choose a style.** A standard list is flat; a [segmented](#segmented) list separates each item into its own container. * **Match the item to its content.** Add [supporting text](#slots), an overline, an avatar or a leading icon to describe what an item is. * **Add behavior when it helps.** Lists can [select](#selection), [reorder](#reordering), [expand](#expandable-items) and reveal [swipe actions](#swipe-actions). ## Anatomy A list holds list items. Each item has a label and slots around it. **Example: A list item with every part filled in** ```html
A
mail Inbox Ada Lovelace Notes on the engine 9:41 AM star ``` ## Examples ### Slots An item's label is its default slot. Put an `md-gb-icon` in `leading`, a circular image or initial in `avatar`, a small line above the label in `overline`, and more detail in `supporting-text`. **Example: Items with a leading icon, an overline and trailing text** ```html mail Inbox Weekly digest Your summary for the last seven days 9:41 AM mail Inbox Trip itinerary Flights, hotel and reservations Yesterday ``` ### Segmented Add `segmented` to show each item in its own container, separated by a small gap. **Example: A segmented list of three items** ```html Apples Bananas Cucumbers ``` ### Non-interactive items Add `static` to an item that only displays information, so it has no hover, focus or press states. **Example: A list of static items with dates** ```html The first computer (ENIAC) 1946 Sputnik launched into space 1957 ``` ### Selection Add `selectable` to let people select several items with a long press, and by tapping while in selection mode. The list fires `itemselectionchange`, and selected items have `checked`. Add `selection-primary` when selecting is the main task, to always show the checkboxes. **Example: A selectable list of photos** ```html image Beach image Forest image Mountains ``` ### Reordering Add `reorderable` to show a drag handle on every item. People can drag it, or tap it and use the move up and move down buttons. The list fires a cancelable `reorder` event. **Example: A reorderable list of recipe steps** ```html Preheat the oven Mix the dough Let it rise Bake for 40 minutes ``` ### Expandable items Add `expandable` to an item and put a nested `md-gb-list` in its `nested` slot. Add `expanded` to start open. **Example: An expandable item with three nested items** ```html checklist Groceries 3 items Bread Milk Eggs ``` ### Swipe actions Put buttons in the `leading-actions` and `trailing-actions` slots to reveal them when people swipe an item. A "more" button and the arrow keys offer the same actions without swiping. **Example: A list item with a pin action and share and archive actions** ```html restaurant Fresh baked breads ``` ### Density Set `density` on the list from `0` (default) down to `-3` to remove 4px of height per step. Keep it off by default and let people opt in. **Example: A list at density -2** ```html Apples Bananas Cucumbers ``` ## Accessibility * A list has `role="list"`, and `role="listbox"` when it is `selectable`. Items have `role="listitem"`. Label a list with `aria-label` or `aria-labelledby` when its purpose isn't clear from the page. * Arrow keys move between items. * In a reorderable list, the drag handle and the move up and move down buttons have labels built from the item's text, and moves are announced to screen readers. Change them with `drag-handle-label`, `move-up-label` and `move-down-label` when you translate the page. * Give swipe action buttons an `aria-label` that names the item, such as "Share Fresh baked breads". * Selecting and reordering must not need a gesture only: the checkboxes, the move buttons and the "more" button are the single-pointer alternatives. **Example: A list labelled Shopping list** ```html Bread Milk ``` ## API reference ### <md-gb-list> A Material Design component. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | density
The density, from 0 (default) to -3. Each step down removes 4px from the items' height (spec foundations Density: "decreasing the top and bottom padding or overall height by 4dp"). Values are clamped to that range. Like md-gb-segmented-button-set's density. | density | ListDensity | | | reorderable
Whether the items can be reordered. Shows a drag handle on every item. | reorderable | boolean | false | | reorderMessages
The screen reader announcements made while reordering. | | ListReorderMessages | LIST_REORDER_MESSAGES | | segmented
Whether to render the list with segmented items. | segmented | boolean | false | | selectable
Whether the user can select several items with a long press (and drag), and by tapping them while in selection mode. | selectable | boolean | false | | selectionPrimary
Whether selecting is the list's primary activity: a selectable list then always shows the selection checkboxes (on desktop). | selection-primary | boolean | false | #### Slots | Slot | Description | | --- | --- | | default | Used to display list items. | #### Events | Event | Description | | --- | --- | | itemselectionchange
Event | When the user changes the selected items of a selectable list (ListSelectionChangeEvent with selected). | | reorder
Event | When the user drops an item at a new position (ListReorderEvent with from, to and item). Cancelable. | #### CSS parts | Part | Description | | --- | --- | | ::part(drop-zone) | The drop target shown while dragging. | | ::part(list) | The list's root element. | #### CSS custom properties | Property | Description | | --- | --- | | --container-shape | | | --gap | | ### <md-gb-list-item> A Material Design component. #### Properties | Property | Attribute | Type | Default | | --- | --- | --- | --- | | checked
Whether the list item is selected. | checked | boolean | false | | disabled
Whether the list item is disabled. | disabled | boolean | false | | dragging
Whether the item is being dragged. Set by the list while reordering. | dragging | boolean | false | | dragHandleLabel
The accessible label prefix of the drag handle; the item's label text is appended (e.g. "Reorder Apples"). | drag-handle-label | string | "Reorder" | | expandable
Whether the item expands to reveal the content in its nested slot. Expandable items are always interactive. | expandable | boolean | false | | expanded
Whether an expandable item is expanded. | expanded | boolean | false | | grabbed
Whether the item is grabbed for reordering without dragging (with the keyboard or a tap on the drag handle). Set by the list; shows the move up and move down buttons. | grabbed | boolean | false | | moveDownLabel
The accessible label prefix of the move down button; the item's label text is appended. | move-down-label | string | "Move down" | | moveUpLabel
The accessible label prefix of the move up button; the item's label text is appended (e.g. "Move up Apples"). | move-up-label | string | "Move up" | | nonInteractive
Whether the list item is non-interactive. | static | boolean | false | | noRevealButton
Hides the "more" button that reveals the swipe actions with a tap. Only set it when the app offers another single-pointer way to reach them (e.g. a menu), as the spec requires one. | no-reveal-button | boolean | false | | reorderable
Whether to show a drag handle to reorder the item within its md-gb-list. Set by the list when the list is reorderable. | reorderable | boolean | false | | revealButtonLabel
The accessible label prefix of the "more" button; the item's label text is appended (e.g. "More actions Apples"). | reveal-button-label | string | "More actions" | | revealed
The side whose swipe actions are revealed, or '' when closed. | revealed | ListItemRevealed | "" | | rovingTabIndex
Set by a parent md-gb-list to make the list a single tab stop with arrow-key navigation (roving tabindex, lists.md Keyboard navigation): 0 on the list's tab stop, -1 on the other items, null (default) for an item outside a list. While set, the item's other controls (drag handle, "more" and move buttons, actions) leave the tab order and are reached with Left/Right. | | number | null | | selectable
Whether the item shows a selection checkbox (hover, or whenever selectionVisible). Set by a selectable parent md-gb-list. | | boolean | false | | selectionVisible
Whether the selection checkbox is always shown: the list sets it when selection is the primary activity or once an item is selected (selection.md, "Click"). Otherwise the checkbox shows on hover. | selection-visible | boolean | false | #### Slots | Slot | Description | | --- | --- | | default | Used to display the item's primary label. | | avatar | Used to display a circular avatar before the item's content. | | leading | Used to display icons and content before the item's main content. | | leading-actions | Buttons revealed by swiping toward the end. | | nested | Nested items or content an expandable item reveals. | | overline | Used to display overline text above the main label. | | supporting-text | Used to display supporting text below the main label. | | trailing | Used to display icons and content after the item's main content. | | trailing-actions | Buttons revealed by swiping toward the start. The last one is the primary action. | | trailing-text | Used to display metadata or text after the item's main content. | #### Events | Event | Description | | --- | --- | | reveal-change
Event | When the user reveals or hides the swipe actions. | | toggle
Event | When the user expands or collapses an expandable item (ToggleEvent). | #### Methods | Method | Description | | --- | --- | | close
() => void | Hides the swipe actions. | | focusDragHandle
() => void | Focuses the item's drag handle, if it has one. | | focusPrimary
() => void | Focuses the item itself (its primary action), or its first control when the item is static or disabled. Used by md-gb-list's arrow keys. | | reveal
(side: "leading" | "trailing") => void | Reveals the swipe actions on one side. | | rowElements
() => HTMLElement[] | The item's focusable elements in visual order (start to end): leading actions, interactive avatar/leading content, the item, interactive trailing content, the "more" button, the move up / move down buttons, the drag handle and the trailing actions. Left/Right move through them. | #### CSS parts | Part | Description | | --- | --- | | ::part(actions) | The container of the revealed actions. | | ::part(drag-handle) | The reorder drag handle. | | ::part(list-item) | The list item's root element. | | ::part(move-down) | The button that moves a grabbed item down. | | ::part(move-up) | The button that moves a grabbed item up. | | ::part(nested) | The expandable region of nested content. | | ::part(reveal-button) | The "more" button that reveals the swipe actions. | #### CSS custom properties | Property | Description | | --- | --- | | --avatar-color | | | --avatar-label | | | --avatar-label-axes | | | --avatar-label-color | | | --avatar-label-tracking | | | --avatar-shape | | | --avatar-size | | | --between-space | | | --bottom-space | | | --container-color | | | --container-height | | | --container-shape | | | --density-step | Height removed per density step (set density on md-gb-list). | | --label-text | | | --label-text-color | | | --label-text-tracking | | | --leading-icon-color | | | --leading-icon-size | | | --leading-space | | | --overline | | | --overline-axes | | | --overline-color | | | --overline-tracking | | | --supporting-text | | | --supporting-text-axes | | | --supporting-text-color | | | --supporting-text-tracking | | | --top-space | | | --trailing-icon-color | | | --trailing-icon-size | | | --trailing-space | | | --trailing-supporting-text | | | --trailing-supporting-text-axes | | | --trailing-supporting-text-color | | | --trailing-supporting-text-tracking | |