0.27.0 • Published 2 years ago

@material/mwc-list v0.27.0

Weekly downloads
6,445
License
Apache-2.0
Repository
github
Last release
2 years ago

<mwc-list> Published on npm

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">user@domain.tld</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

NameDescription
defaultContent to display in the lists internal <ul> element.

mwc-list-item

NameDescription
graphicFirst tile graphic to display when graphic attribute is defined.
metaLast tile meta icon or text to display when hasMeta is true.
secondarySecondary text displayed below primary text of a two-line list item.
defaultPrimary 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

NameTypeDefaultDescription
activatablebooleanfalseSets activated attribute on selected items which provides a focus-persistent highlight.
rootTabbablebooleanfalseWhen true, sets tabindex="0" on the internal list. Otherwise sets tabindex="-1".
multibooleanfalseWhen true, enables selection of multiple items. This will result in index being of type Set<number> and selected returning ListItemBase[].
wrapFocusbooleanfalseWhen 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.
itemRolesstring\|nullnullDetermines what role attribute to set on all list items.
innerAriaLabelstring\|nullnullARIA label of the internal <ul> element.
innerRolestring\|nullnullRole of the internal <ul> element.
noninteractivebooleanfalseWhen true, disables focus and pointer events (thus ripples) on the list. Used for display-only lists.
itemsListItemBase[] (readonly)*[]All list items that are available for selection. Eligible items have the [mwc-list-item] attribute which ListItemBase applies automatically.
selectedSelectedType (readonly)*nullCurrently-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.
indexMWCListIndex (readonly)**-1Index / 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

NameTypeDefaultDescription
valuestring''Value associated with this list item (used by mwc-select).
groupstring\|nullnullUsed to group items together (used by mwc-menu for menu selection groups and mwc-radio-list-element).
tabindexnumber-1Reflects tabindex and sets internal tab indices.
disabledbooleanfalseReflects disabled and sets internal disabled attributes.
twolinebooleanfalseActivates the two-line variant and enables the secondary slot.
activatedbooleanfalseActivates focus-persistent ripple.
graphicGraphicType*nullDetermines which graphic layout to show and enables the graphic slot.
multipleGraphicsbooleanfalseAllows arbitrary width for multiple slotted graphics.
hasMetabooleanfalseActivates the meta layout tile and enables the meta slot.
noninteractivebooleanfalseDisables focus and pointer events for the list item.
selectedbooleanfalseDenotes that the list item is selected.
textstring (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.

NameTypeDefaultDescription
leftbooleanfalseDisplays the checkbox on the left. Overrides graphic.
graphicGraphicType*'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.

NameTypeDefaultDescription
leftbooleanfalseDisplays the checkbox on the left. Overrides graphic.
graphicGraphicType*'control'Determines which graphic layout to show and enables the graphic slot when value is not control or null.
groupstring\|nullnullUsed 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

NameDescription
select(index: MWCListIndex) => voidSelects the elements at the given index / indices.
toggle(index: number, force?: boolean) => voidToggles the selected index, and forcibly selects or deselects the value of force if attribute is provided.
getFocusedItemIndex() => numberReturns the index of the currently-focused item. -1 if none are focused.
focusItemAtIndex(index) => voidFocuses the item at the given index and manages tabindex on all other items.
layout(updateItems = true) => voidResets 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 NameTargetDetailDescription
actionmwc-listActionDetail*Fired when a selection has been made via click or keyboard aciton.
selectedmwc-listSelectedDetail**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 NameTargetDetailDescription
request-selectedmwc-list-itemRequestSelectedDetail*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 NameTargetDetailDescription
request-selectedmwc-list-itemRequestSelectedDetailFired upon click. Requests selection from the mwc-list.

mwc-radio-list-item

Event NameTargetDetailDescription
request-selectedmwc-list-itemRequestSelectedDetailFired upon click and on internal mwc-radio's checked event. Requests selection from the mwc-list.

CSS Custom Properties

mwc-list

NameDefaultDescription
--mdc-list-vertical-padding8pxPadding before and after the first and last list items.
--mdc-list-side-padding16pxAdjusts the padding of the [padded] list dividers (also propagates to mwc-list-item).
--mdc-list-inset-margin72pxAdjusts the left inset padding of an [inset] list divider. Typically used for dividing list items with icons.

mwc-list-item

NameDefaultDescription
--mdc-list-side-padding16pxSide padding of the list item.
--mdc-list-item-meta-size24pxLine height of the meta icon or text and width & height of the slotted parent wrapper.
--mdc-list-item-graphic-size24px,40px,56pxLine 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-margin16px,32pxMargin 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.

NameDescription
--mdc-theme-primaryColor of the activated ripple and primary text color when activated.
--mdc-theme-on-surfaceDisabled text color.
--mdc-theme-text-icon-on-backgroundColor of the graphic icon (if graphic is text icon).
--mdc-theme-text-primary-on-backgroundColor of the primary text if not activated.
--mdc-theme-text-secondary-on-backgroundColor of the secondary text if not activated.
--mdc-theme-hint-on-backgroundColor 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

fundwave-fund-management@material/mwc-menu@material/mwc-select@simplr-wc/listsimplr-components@netzoio/web-componentsopenstamanager@everything-registry/sub-chunk-584open-scdkt-playground-elementslit-p2pholochain-file-storageholochain-mutual-creditholochain-profilesholochain-social-triangulationimprov-wifi-serial-sdk@iooxa/components@iooxa/ink-basic@ioperato/process-modellerhomeassistant-frontend-racelandjsui-componentsjupyter_pixanojvx-multiselectmeteoalarm-cardplayground-elementsplayground-elements-ashruhil-ui@dwane-vonage/dwanes-contacts@dwane-vonage/vve-activities@dwane-vonage/vve-closed-captions@dwane-vonage/vve-participants@erixhens/annotator@esui/material-components@equinor/fusion-wc-list@fw-components/fw-avatar@formsey/fields-material@fortit/fwc-chip-list@fmsim/layout-view@infinitebrahmanuniverse/nolb-_mate@finastra/list@hydrofoil/shaperone-wc-materialvve-breakoutvve-participants@jsview/material-componentswc-range-datepickerwces-form-builderyew-material-scriptsyido-elementsux-hub-entity-menuux-hub-product-card@lordoftheflies/plutonium-styles@hass-ada/frontend-liteswag-tag-mwctaskana-workplace-libscoped-material-components@leavittsoftware/leavitt-elements@leavittsoftware/leavitt-file-explorer@leavittsoftware/titanium-address-input@leavittsoftware/titanium-data-table@leavittsoftware/titanium-date-range-selector@openenergytools/scl-wizarding@pixano/core@mothepro/lit-sets@things-factory/process-modeller@things-factory/board-ui@openscd/open-scd-core@openscd/oscd-filtered-list@openscd/oscd-tree-explorer@openscd/oscd-tree-grid@smart-design-platform/enthalpy@smart-design-platform/evaluator@smart-design-platform/process-modeller@sted/enthalpy@sted/evaluator@sted/process-modeller@takeramagan/hotel-library@wces/autocomplete@wces/dot-menu@wces/form-builder@wces/jsui-material@web-mjs/material-components@web-mjs/material-web-components@vonage/vwc-list@apihub/process-modeller@allenporter/recurrence-rule-editor@accordion/accordion-graph@aurodesignsystem/auro-datepicker@blackpurl/web-components@bluetensor/annotatorcloudbees-casc-server-plugin-ui@batchforce/core@backlight-dev/aodocs.aodocs-design-systemcorgy-frontend
0.27.0

2 years ago

0.26.1

2 years ago

0.26.0

2 years ago

0.25.3

2 years ago

0.25.2

2 years ago

0.25.1

3 years ago

0.23.0

3 years ago

0.22.1

3 years ago

0.21.0

3 years ago

0.20.0

3 years ago

0.19.1

3 years ago

0.19.0

3 years ago

0.18.0

4 years ago

0.17.2

4 years ago

0.17.0

4 years ago

0.16.1

4 years ago

0.15.0

4 years ago

0.14.1

4 years ago

0.14.0

4 years ago

0.13.0

4 years ago