@material/list
Advanced tools
@material/list is a package from the Material Design Components (MDC) library that provides a set of components and utilities for creating lists with Material Design styling. It allows developers to create various types of lists, such as single-line, two-line, and three-line lists, with support for interactive elements like checkboxes, radio buttons, and icons.
Single-line List
This feature allows you to create a single-line list with Material Design styling. The `singleSelection` property enables single item selection within the list.
import { MDCList } from '@material/list';
const list = new MDCList(document.querySelector('.mdc-list'));
list.singleSelection = true;
Two-line List
This feature allows you to create a two-line list where each list item can have a primary and secondary text. The `wrapFocus` property ensures that focus wraps from the last item back to the first item when navigating with the keyboard.
import { MDCList } from '@material/list';
const list = new MDCList(document.querySelector('.mdc-list'));
list.wrapFocus = true;
List with Checkboxes
This feature allows you to create a list where each item includes a checkbox. The code initializes the list and maps over each list item to initialize the checkboxes.
import { MDCList } from '@material/list';
const list = new MDCList(document.querySelector('.mdc-list'));
list.listElements.map((listItemEl) => new MDCCheckbox(listItemEl.querySelector('.mdc-checkbox')));
List with Icons
This feature allows you to create a list where each item includes an icon button. The code initializes the list and maps over each list item to initialize the icon buttons.
import { MDCList } from '@material/list';
const list = new MDCList(document.querySelector('.mdc-list'));
list.listElements.map((listItemEl) => new MDCIconButtonToggle(listItemEl.querySelector('.mdc-icon-button')));
react-list is a versatile library for rendering lists in React applications. It supports infinite scrolling, variable heights, and other advanced features. Compared to @material/list, react-list is more focused on performance and flexibility in rendering large lists, but it does not provide built-in Material Design styling.
react-virtualized is a library for efficiently rendering large lists and tabular data in React. It offers features like lazy loading, infinite scrolling, and dynamic row heights. While it excels in performance for large datasets, it does not include Material Design components like @material/list.
react-window is a lightweight library for rendering large lists and grids in React. It is similar to react-virtualized but with a smaller footprint and simpler API. It focuses on performance and efficiency, but like react-virtualized, it does not provide Material Design styling out of the box.
MDC List provides styles which implement Material Design Lists - "A single continuous column of tessellated subdivisions of equal width." Both single-line and two-line lists are supported (with three-line lists coming soon). MDC Lists are design to be accessible and RTL aware.
npm install --save @material/list
A basic lists consists simply of the list itself, and list items taking up one line.
<ul class="mdc-list">
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
</ul>
A list will flip its direction if it is placed within an ancestor element containing a dir
attribute with value "rtl". This applies to all lists regardless of type.
<html dir="rtl">
<!-- ... -->
<ul class="mdc-list">
<!-- Hebrew for 'item in list' -->
<li class="mdc-list-item">פריט ברשימה</li>
</ul>
</html>
Like other MDC-Web components, lists support dark mode either when an mdc-list--theme-dark class is
attached to the root element, or the element has an ancestor with class mdc-theme--dark.
<html class="mdc-theme--dark">
<!-- ... -->
<ul class="mdc-list">
<li class="mdc-list-item">A list item on a dark background</li>
</ul>
</html>
Lists can be made more compact by using the mdc-list--dense modifier class.
<ul class="mdc-list mdc-list--dense">
<!-- ... -->
</ul>
While in theory you can add any number of "lines" to a list item, you can use the mdc-list--two-line combined with some extra markup around the text to style a list in the two-line list style as defined by the spec (see "Two-line lists").
<ul class="mdc-list mdc-list--two-line">
<li class="mdc-list-item">
<span class="mdc-list-item__text">
<span class="mdc-list-item__text__primary">Two-line item</span>
<span class="mdc-list-item__text__primary">Secondary text</span>
</span>
</li>
</ul>
As mentioned in the spec, lists can contain primary and secondary actions. It can also contain things such as avatars, icons, interactive controls, etc. We call these items detail items. Lists can contain 1 start detail item and/or 1 end detail item that are positioned at the start and end of the list, respectively. These items are correctly flipped in RTL contexts.
N.B. Please keep accessibility in mind when using things such as icons / icon fonts for detail elements. Font Awesome has excellent guidelines for this.
You can add a start detail using an element with class mdc-list-item__start-detail class.
<ul class="mdc-list">
<li class="mdc-list-item">
<i class="mdc-list-item__start-detail material-icons" aria-hidden="true">network_wifi</i>
Wi-Fi
</li>
<li class="mdc-list-item">
<i class="mdc-list-item__start-detail material-icons" aria-hidden="true">bluetooth</i>
Bluetooth
</li>
<li class="mdc-list-item">
<i class="mdc-list-item__start-detail material-icons" aria-hidden="true">data_usage</i>
Data Usage
</li>
</ul>
You can use the mdc-list--avatar-list modifier class to style the start detail elements as what
the spec calls "avatars" - large, circular details that lend themselves well to contact images,
profile pictures, etc.
<h2>Contacts</h2>
<ul class="mdc-list mdc-list--avatar-list">
<li class="mdc-list-item">
<img class="mdc-list-item__start-detail" src="/users/1/profile_pic.png"
width="56" height="56" alt="Picture of Janet Perkins">
Janet Perkins
</il>
<li class="mdc-list-item">
<img class="mdc-list-item__start-detail" src="/users/2/profile_pic.png"
width="56" height="56" alt="Picture of Mary Johnson">
Mary Johnson
</il>
<li class="mdc-list-item">
<img class="mdc-list-item__start-detail" src="/users/3/profile_pic.png"
width="56" height="56" alt="Picture of Peter Carlsson">
Peter Carlsson
</il>
</ul>
End details can be added in a similar way to start details. Place an element after the text
with a mdc-list-item__end-detail class.
<h2>Contacts</h2>
<ul class="mdc-list">
<li class="mdc-list-item">
Janet Perkins
<a href="#" class="mdc-list-item__end-detail material-icons"
aria-label="Remove from favorites" title="Remove from favorites">
favorite
</a>
</li>
<li class="mdc-list-item">
Mary Johnson
<a href="#" class="mdc-list-item__end-detail material-icons"
aria-label="Add to favorites" title="Add to favorites">
favorite_border
</a>
</li>
<li class="mdc-list-item">
Janet Perkins
<a href="#" class="mdc-list-item__end-detail material-icons"
aria-label="Add to favorites" title="Add to favorites">
favorite_border
</a>
</li>
</ul>
Start and end details can be combined easily. Check out the list demo for many examples of how details can be configured.
NOTE: If using controls such as a switch (TK!) within a list detail, you may need to override the width and height styles set on the detail element.
MDC List supports adding ripples to mdc-list-item elements, for example in the case of a nav menu.
To add ripples to lists, simply attach a ripple to all list items. Note that this can be easily done
via mdc-auto-init when using the material-components-web.
<nav class="mdc-list">
<a href="/wifi" class="mdc-list-item" data-mdc-auto-init="MDCRipple">
<i class="material-icons mdc-list-item__start-detail" aria-hidden="true">
network_wifi
</i>
Wi-Fi
</a>
<a href="/bluetooth" class="mdc-list-item" data-mdc-auto-init="MDCRipple">
<i class="material-icons mdc-list-item__start-detail" aria-hidden="true">
bluetooth
</i>
Bluetooth
</a>
<a href="/data-usage" class="mdc-list-item" data-mdc-auto-init="MDCRipple">
<i class="material-icons mdc-list-item__start-detail" aria-hidden="true">
data_usage
</i>
Data Usage
</a>
</nav>
<script>
mdc.autoInit();
</script>
MDC List contains an mdc-list-divider classes which can be used as full-width or inset
subdivisions either within lists themselves, or event standalone between related groups of content.
To use within lists, simply add the mdc-list-divider class to a list item.
<ul class="mdc-list">
<li class="mdc-list-item">Item 1 - Division 1</li>
<li class="mdc-list-item">Item 2 - Division 1</li>
<li class="mdc-list-item">Item 3 - Division 1</li>
<li role="separator" class="mdc-list-divider"></li>
<li class="mdc-list-item">Item 1 - Division 2</li>
<li class="mdc-list-item">Item 1 - Division 2</li>
</ul>
Note the
role="separator"attribute on the list divider. It is important to include this so that assistive technology can be made aware that this is a presentational element and is not meant to be included as an item in a list. Note thatseparatoris indeed a valid role forlielements.
In order to make separators inset, add a mdc-list-divider--inset modifier class to it.
<ul class="mdc-list">
<li class="mdc-list-item">Item 1 - Division 1</li>
<li class="mdc-list-item">Item 2 - Division 1</li>
<li class="mdc-list-item">Item 3 - Division 1</li>
<li role="separator" class="mdc-list-divider mdc-list-divider--inset"></li>
<li class="mdc-list-item">Item 1 - Division 2</li>
<li class="mdc-list-item">Item 1 - Division 2</li>
</ul>
Inset dividers are useful when working with lists which have start details.
Multiple related lists can be grouped together using the mdc-list-group class on a containing
element. mdc-list-divider elements can be used in these groups between lists to help
differentiate them.
<div class="mdc-list-group">
<h3 class="mdc-list-group__subheader">List 1</h3>
<ul class="mdc-list">
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
</ul>
<hr class="mdc-list-divider">
<h3 class="mdc-list-group__subheader">List 2</h3>
<ul class="mdc-list">
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
<li class="mdc-list-item">Single-line item</li>
</ul>
</div>
While hinted at within the spec, bordered lists - where each list item has a border around it - are not officially part of the list component spec. However, they seem to be used often in web applications, especially those suited more for desktop. The following example shows how to add borders to lists.
<style>
.my-bordered-list {
/* remove the side padding. we'll be placing it around the item instead. */
padding-right: 0;
padding-left: 0;
}
.my-bordered-list .mdc-list-item {
/* Add the list side padding padding to the list item. */
padding: 0 16px;
/* Add a border around each element. */
border: 1px solid rgba(0, 0, 0, .12);
}
/* Ensure adjacent borders don't collide with one another. */
.my-bordered-list .mdc-list-item:not(:first-child) {
border-top: none;
}
</style>
<!-- ... -->
<ul class="mdc-list my-bordered-list">
<li class="mdc-list-item">Item 1</li>
<li class="mdc-list-item">Item 2</li>
<li class="mdc-list-item">Item 3</li>
</ul>
In some cases, you may want start/end details to be positioned differently than the center. An
example of this is in this mock showing a timestamp being positioned in the top-right corner
or a list item. You can easily do this by adding an align-self rule to the details you'd like
styled this way. For example, given a timestamp class for an end detail:
.mdc-list-item__end-detail.timestamp {
/* Lock to top of container. */
align-self: flex-start;
}
Alternatively, if you have multiple items you'd like to put into a detail, you can give it flex positioning and set its flex direction to column. This will allow you to stack items within an end detail one on top of another.
For example, let's say you're building a messaging app and, naturally, you want a list of messages as part of your UI. You're designer wants a timestamp in the top-right corner and an "unread" indicator below it corner.
The html for this can be easily added
<ul class="mdc-list mdc-list--two-line msgs-list">
<li class="mdc-list-item">
<span class="mdc-list-item__text">
<span class="mdc-list-item__text__primary">Ali Connors</span>
<span class="mdc-list-item__text_secondary">Lunch this afternoon? I was...</span>
</span>
<span class="mdc-list-item__end-detail">
<time datetime="2014-01-28T04:36:00.000Z">4:36pm</time>
<i class="material-icons" arial-label="Unread message">chat_bubble</i>
</span>
</li>
<!-- ... -->
</ul>
And the basic CSS is relatively trivial
.msgs-list .mdc-list-item__end-detail {
width: auto;
height: auto;
display: inline-flex;
flex-direction: column;
align-items: flex-end;
}
FAQs
The Material Components for the web list component
The npm package @material/list receives a total of 164,573 weekly downloads. As such, @material/list popularity was classified as popular.
We found that @material/list demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.