@material/mwc-list

<mwc-list>

IMPORTANT: The Material Web Components are a work in progress and subject to major changes until 1.0 release.

Lists are continuous, vertical indexes of text or images.

Material Design Guidelines: lists

Demo

Installation

npm install @material/mwc-list

NOTE: The Material Web Components are distributed as ES2017 JavaScript Modules, and use the Custom Elements API. They are compatible with all modern browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional tooling step is required to resolve bare module specifiers, as well as transpilation and polyfills for IE11. See here for detailed instructions.

Example usage

Basic

<mwc-list>
  <mwc-list-item>Item 0</mwc-list-item>
  <mwc-list-item>Item 1</mwc-list-item>
  <mwc-list-item>Item 2</mwc-list-item>
  <mwc-list-item>Item 3</mwc-list-item>
</mwc-list>

<script type="module">
  import '@material/mwc-list/mwc-list.js.js';
  import '@material/mwc-list/mwc-list-item.js.js';
</script>

Activatable

<mwc-list activatable>
  <mwc-list-item>Item 0</mwc-list-item>
  <mwc-list-item selected activated>Item 1</mwc-list-item>
  <mwc-list-item>Item 2</mwc-list-item>
  <mwc-list-item>Item 3</mwc-list-item>
</mwc-list>

Multi-selectable (activatable)

<mwc-list activatable multi>
  <mwc-list-item>Item 0</mwc-list-item>
  <mwc-list-item selected activated>Item 1</mwc-list-item>
  <mwc-list-item>Item 2</mwc-list-item>
  <mwc-list-item selected activated>Item 3</mwc-list-item>
</mwc-list>

Leading Graphic

Note: it is not recommended to mix graphic sizes in the same list.

<style>
  /* invert icon color */
  mwc-icon {
    background-color: gray;
    color: white;
  }
</style>

<mwc-list>
  <mwc-list-item graphic="avatar">
    <span>Avatar graphic</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
  <mwc-list-item graphic="icon">
    <span>Icon graphic</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
  <mwc-list-item graphic="medium">
    <span>medium graphic</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
  <mwc-list-item graphic="large">
    <span>large graphic</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
</mwc-list>

<script type="module">
  import '@material/mwc-list/mwc-list-item.js.js';
  import '@material/mwc-list/mwc-list.js.js';
  import '@material/mwc-icon/mwc-icon.js';
</script>

Meta Icon

<mwc-list>
  <mwc-list-item hasMeta>
    <span>Location A</span>
    <mwc-icon slot="meta">info</mwc-icon>
  </mwc-list-item>
  <mwc-list-item hasMeta>
    <span>Location B</span>
    <mwc-icon slot="meta">info</mwc-icon>
  </mwc-list-item>
  <mwc-list-item hasMeta>
    <span>Location C</span>
    <mwc-icon slot="meta">info</mwc-icon>
  </mwc-list-item>
  <mwc-list-item hasMeta>
    <span>Location D</span>
    <mwc-icon slot="meta">info</mwc-icon>
  </mwc-list-item>
</mwc-list>

Two-Line

<mwc-list>
  <mwc-list-item twoline>
    <span>Item 0</span>
    <span slot="secondary">Secondary line</span>
  </mwc-list-item>
  <mwc-list-item twoline>
    <span>Item 1</span>
    <span slot="secondary">Secondary line</span>
  </mwc-list-item>
  <mwc-list-item twoline>
    <span>Item 2</span>
    <span slot="secondary">Secondary line</span>
  </mwc-list-item>
  <mwc-list-item twoline>
    <span>Item 3</span>
    <span slot="secondary">Secondary line</span>
  </mwc-list-item>
</mwc-list>

Dividers

Dividers must have the divider attribute and it is recommended to add role="separator" for screen readers. There are 3 variants of dividers, full-width (default), padded (respects list padding), and inset (left-padding respects avatar and icon paddding). These variants can be mixed.

<mwc-list>
  <mwc-list-item>Item 0</mwc-list-item>
  <li divider role="separator"></li>
  <mwc-list-item>Item 1</mwc-list-item>
  <li divider padded role="separator"></li>
  <mwc-list-item>Item 2</mwc-list-item>
  <li divider padded role="separator"></li>
  <mwc-list-item>Item 3</mwc-list-item>
  <li divider padded role="separator"></li>
  <mwc-list-item graphic="avatar">
    <span>avatar item</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
  <li divider inset padded role="separator"></li>
  <mwc-list-item graphic="avatar">
    <span>avatar item</span>
    <mwc-icon slot="graphic">folder</mwc-icon>
  </mwc-list-item>
</mwc-list>

Checklist

mwc-check-list-item inherits from mwc-list-item, so it will share a similar API to mwc-list-item.

<mwc-list multi>
  <mwc-check-list-item selected>Item 0</mwc-check-list-item>
  <mwc-check-list-item selected>Item 1</mwc-check-list-item>
  <li divider role="separator" padded></li>
  <mwc-check-list-item left selected>Item 2 (left)</mwc-check-list-item>
  <mwc-check-list-item left>Item 3 (left)</mwc-check-list-item>
</mwc-list>

<script type="module">
  import '@material/mwc-list/mwc-check-list-item.js.js';
  import '@material/mwc-list/mwc-list.js.js';
</script>

Radio List

mwc-radio-list-item inherits from mwc-list-item, so it will share a similar API to mwc-list-item.

Setting group on the radio-list-item will group those mwc-radios together across the same Document.

<mwc-list>
  <mwc-radio-list-item group="a" selected>Item 0</mwc-radio-list-item>
  <mwc-radio-list-item group="a">Item 1</mwc-radio-list-item>
  <li divider padded role="separator"></li>
  <mwc-radio-list-item left group="a">Item 2 (left)</mwc-radio-list-item>
  <mwc-radio-list-item left group="a">Item 3 (left)</mwc-radio-list-item>
</mwc-list>

Multi Radio List

A radio list can also have multi.

<mwc-list multi>
  <mwc-radio-list-item group="b">Item 0</mwc-radio-list-item>
  <mwc-radio-list-item group="b" selected>Item 1</mwc-radio-list-item>
  <li divider role="separator"></li>
  <mwc-radio-list-item group="c" selected>Item 2</mwc-radio-list-item>
  <mwc-radio-list-item group="c">Item 3</mwc-radio-list-item>
</mwc-list>
<script type="module">
  import '@material/mwc-list/mwc-radio-list-item.js.js';
  import '@material/mwc-list/mwc-list.js.js';
</script>

Item Noninteractive

Setting a list-item to non-interactive will disable focus and pointer events on the item, and it will no longer be considered for selection.

<style>
  .inverted {
    background-color: gray;
    color: white;
  }
</style>
<mwc-list>
  <mwc-list-item twoline graphic="avatar" noninteractive>
    <span>User Name</span>
    <span slot="secondary">[e-mail]</span>
    <mwc-icon slot="graphic" class="inverted">tag_faces</mwc-icon>
  </mwc-list-item>
  <li divider role="separator"></li>
  <mwc-list-item graphic="icon">
    <slot>FAQ</slot>
    <mwc-icon slot="graphic">help_outline</mwc-icon>
  </mwc-list-item>
  <mwc-list-item graphic="icon">
    <slot>Sign out</slot>
    <mwc-icon slot="graphic">exit_to_app</mwc-icon>
  </mwc-list-item>
</mwc-list>

Styled

<style>
  #styled {
    --mdc-theme-primary: red;
    --mdc-list-vertical-padding: 0px;
    --mdc-list-side-padding: 30px;
    border-radius: 10px;
    overflow: hidden;
  }
</style>
<mwc-list activatable id="styled">
  <mwc-list-item selected>Item 0</mwc-list-item>
  <mwc-list-item>Item 1</mwc-list-item>
  <mwc-list-item>Item 2</mwc-list-item>
  <mwc-list-item>Item 3</mwc-list-item>
</mwc-list>

Styled No-ripple

For more-control on styling, you may want to disable the ripple. Internally list-item uses mwc-ripple. You can make the ripple invisible using its custom properties detailed in mwc-ripple's documentation. In this case, it may be simple to just set --mdc-ripple-color to transparent.

<style>
  /* disable ripple */
  #styledr {
    --mdc-ripple-color: transparent;
  }

  #styledr > * {
    transition: background-color .2s, color .2s;
  }

  #styledr [selected] {
    background-color: rgb(33, 33, 33);
    color: white;
  }

  #styledr [mwc-list-item]:not([selected]):hover,
  #styledr [mwc-list-item]:not([selected]):focus {
    background-color: rgba(33, 33, 33, 0.3);
  }

  #styledr [mwc-list-item]:not([selected]):active {
    background-color: rgba(33, 33, 33, 0.4);
  }

  #styledr [mwc-list-item][selected]:hover,
  #styledr [mwc-list-item][selected]:focus {
    background-color: rgba(33, 33, 33, 0.9);
  }

  #styledr [mwc-list-item][selected]:active {
    background-color: rgba(33, 33, 33, 0.8);
  }
</style>

<mwc-list id="styledr">
  <mwc-list-item selected>Item 0</mwc-list-item>
  <mwc-list-item>Item 1</mwc-list-item>
  <mwc-list-item>Item 2</mwc-list-item>
  <mwc-list-item>Item 3</mwc-list-item>
</mwc-list>

API

Slots

mwc-list

Name	Description
default	Content to display in the lists internal <ul> element.

mwc-list-item

Name	Description
graphic	First tile graphic to display when graphic attribute is defined.
meta	Last tile meta icon or text to display when hasMeta is true.
secondary	Secondary text displayed below primary text of a two-line list item.
default	Primary text to display in the list item. Note, text must be wrapped in an inline node to be styled for disabled variant.

Properties/Attributes

mwc-list

Name	Type	Default	Description
activatable	boolean	false	Sets activated attribute on selected items which provides a focus-persistent highlight.
rootTabbable	boolean	false	When true, sets tabindex="0" on the internal list. Otherwise sets tabindex="-1".
multi	boolean	false	When true, enables selection of multiple items. This will result in index being of type Set<number> and selected returning ListItemBase[].
wrapFocus	boolean	false	When true, pressing up on the keyboard when focused on the first item will focus the last item and down when focused on the last item will focus the first item.
itemRoles	string|null	null	Determines what role attribute to set on all list items.
innerAriaLabel	string|null	null	ARIA label of the internal <ul> element.
innerRole	string|null	null	Role of the internal <ul> element.
noninteractive	boolean	false	When true, disables focus and pointer events (thus ripples) on the list. Used for display-only lists.
items	ListItemBase[] (readonly)*	[]	All list items that are available for selection. Eligible items have the [mwc-list-item] attribute which ListItemBase applies automatically.
selected	SelectedType (readonly)*	null	Currently-selected list item(s). When multi is true, selected is of type ListItemBase[] and when false, selected is of type ListItemBase. selected is null when no item is selected.
index	MWCListIndex (readonly)**	-1	Index / indices of selected item(s). When multi is true, index is of type number and when false, index is of type Set<number>. Unset indicies are -1 and empty Set<number> for single and multi selection respectively.

* SelectedType is equivaalent to type ListItemBase|ListItemBase[]|null. ListItemBase is the base class of mwc-list-item of which both mwc-check-list-item and mwc-radio-list-item also inherit from.

** MWCListIndex is equivalent to type number|Set<number>.

mwc-list-item

Name	Type	Default	Description
value	string	''	Value associated with this list item (used by mwc-select).
group	string|null	null	Used to group items together (used by mwc-menu for menu selection groups and mwc-radio-list-element).
tabindex	number	-1	Reflects tabindex and sets internal tab indices.
disabled	boolean	false	Reflects disabled and sets internal disabled attributes.
twoline	boolean	false	Activates the two-line variant and enables the secondary slot.
activated	boolean	false	Activates focus-persistent ripple.
graphic	GraphicType*	null	Determines which graphic layout to show and enables the graphic slot.
multipleGraphics	boolean	false	Allows arbitrary width for multiple slotted graphics.
hasMeta	boolean	false	Activates the meta layout tile and enables the meta slot.
noninteractive	boolean	false	Disables focus and pointer events for the list item.
selected	boolean	false	Denotes that the list item is selected.
text	string (readonly)	''	Trimmed textContent of the list item.

* GraphicType is equivalent to the type 'avatar'|'icon'|'medium'|'large'|'control'|null.

mwc-check-list-item

Note: mwc-check-list-item inherits from ListItemBase which is the base class of mwc-list-item, so all properties in mwc-list-item will be available on mwc-check-list-item.

Name	Type	Default	Description
left	boolean	false	Displays the checkbox on the left. Overrides graphic.
graphic	GraphicType*	'control'	Determines which graphic layout to show and enables the graphic slot when value is not control or null.

* GraphicType is equivalent to the type 'avatar'|'icon'|'medium'|'large'|'control'|null.

mwc-radio-list-item

Note: mwc-radio-list-item inherits from ListItemBase which is the base class of mwc-list-item, so all properties in mwc-list-item will be available on mwc-radio-list-item.

Name	Type	Default	Description
left	boolean	false	Displays the checkbox on the left. Overrides graphic.
graphic	GraphicType*	'control'	Determines which graphic layout to show and enables the graphic slot when value is not control or null.
group	string|null	null	Used to group the internal mwc-radios together (also used by mwc-menu for selection groups).

* GraphicType is equivalent to the type 'avatar'|'icon'|'medium'|'large'|'control'|null.

Methods

Name	Description
select(index: MWCListIndex) => void	Selects the elements at the given index / indices.
toggle(index: number, force?: boolean) => void	Toggles the selected index, and forcibly selects or deselects the value of force if attribute is provided.
getFocusedItemIndex() => number	Returns the index of the currently-focused item. -1 if none are focused.
focusItemAtIndex(index) => void	Focuses the item at the given index and manages tabindex on all other items.
layout(updateItems = true) => void	Resets tabindex on all items and will update items model if provided true. It may be required to call layout if selectability of an element is dynamically changed. e.g. [mwc-list-item] attribute is removed from a list item or noninteractive is dynamically set on a list item.

Events

mwc-list

Event Name	Target	Detail	Description
action	mwc-list	ActionDetail*	Fired when a selection has been made via click or keyboard aciton.
selected	mwc-list	SelectedDetail**	Fired when a selection has been made. index is the selected index (will be of type Set<number> if multi and number if single), and diff (of type IndexDiff**) represents the diff of added and removed indices from previous selection.

* ActionDetail is an interface of the following type:

interface ActionDetail {
  index: number;
}

** SelectedDetail is an interface of the following type:

interface SelectedDetail<T extends MWCListIndex = MWCListIndex> {
  index: T;
  diff: T extends Set<number> ? IndexDiff: undefined;
}

** IndexDiff is an interface of the following type:

interface IndexDiff {
  added: number[];
  removed: number[];
}

It may be easier to use SelectedEvent which is of type SingleSelectedEvent|MultiSelectedEvent.

SingleSelectedEvent is of type CustomEvent<SelectedDetail<number>>

MultiSelectedEvent is of type CustomEvent<SelectedDetail<Set<number>>>

If you listen for a selected event you may be able to use the following pattern:

import '@material/mwc-list/mwc-list.js';
import {isEventMulti} from '@material/mwc-list/mwc-list.js';

const onSelected = (evt: SelectedEvent) => {
  if (isEventMulti(evt)) {
    // Typescript will infer evt as {index: Set<number>, diff: IndexDiff}
    ...
  } else {
    // Typescript will infer evt as {index: number, diff: undefined}
    ...
  }
};

mwcList.addEventListener('selected', onSelected);

mwc-list-item

Event Name	Target	Detail	Description
request-selected	mwc-list-item	RequestSelectedDetail*	Fired upon click and when selected property is changed. Requests selection from the mwc-list.

* RequestSelectedDetail is an interface of the following type:

interface RequestSelectedDetail {
  selected: boolean;
  source: 'interaction'|'property';
}

mwc-check-list-item

Event Name	Target	Detail	Description
request-selected	mwc-list-item	RequestSelectedDetail	Fired upon click. Requests selection from the mwc-list.

mwc-radio-list-item

Event Name	Target	Detail	Description
request-selected	mwc-list-item	RequestSelectedDetail	Fired upon click and on internal mwc-radio's checked event. Requests selection from the mwc-list.

CSS Custom Properties

mwc-list

Name	Default	Description
--mdc-list-vertical-padding	8px	Padding before and after the first and last list items.
--mdc-list-side-padding	16px	Adjusts the padding of the [padded] list dividers (also propagates to mwc-list-item).
--mdc-list-inset-margin	72px	Adjusts the left inset padding of an [inset] list divider. Typically used for dividing list items with icons.

mwc-list-item

Name	Default	Description
--mdc-list-side-padding	16px	Side padding of the list item.
--mdc-list-item-meta-size	24px	Line height of the meta icon or text and width & height of the slotted parent wrapper.
--mdc-list-item-graphic-size	24px,40px,56px	Line height of the graphic and width & height of the slotted parent wrapper. 24px when graphic is "icon". 40px when graphic is "avatar". 56px when graphic is "medium", and "large".
--mdc-list-item-graphic-margin	16px,32px	Margin between the text and graphic. 16px when graphic is "avatar", "medium", "large", and "control". 32px when graphic is "icon".

mwc-list-item internally uses mwc-ripple and thus exposes all of the custom properties in mwc-ripple's documentation with the exception of --mdc-ripple-color being overriden as --mdc-theme-primary when mwc-list-item is activated.

Global Custom Properties

This component exposes the following global theming custom properties.

Name	Description
--mdc-theme-primary	Color of the activated ripple and primary text color when activated.
--mdc-theme-on-surface	Disabled text color.
--mdc-theme-text-icon-on-background	Color of the graphic icon (if graphic is text icon).
--mdc-theme-text-primary-on-background	Color of the primary text if not activated.
--mdc-theme-text-secondary-on-background	Color of the secondary text if not activated.
--mdc-theme-hint-on-background	Color of the meta (if is text or text icon).
--mdc-typography-subtitle1-<PROPERTY>	Styles the typography of a list item.
--mdc-typography-body2-<PROPERTY>	Styles the typography of a list item's secondary text.
--mdc-typography-caption-<PROPERTY>	Styles the typography of a list item's icon and meta text.

Additional references

• MDC Web lists