Security News
Combatting Alert Fatigue by Prioritizing Malicious Intent
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
@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 planned). MDC Lists are designed to be accessible and RTL aware.
npm install --save @material/list
A basic list 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>
By default, list items receive styles for hover, focus, and press states (including the ripple effect if
MDCRipple
is instantiated). It is possible to opt out of these styles by adding the mdc-list--non-interactive
modifier to the parent list.
Note: In order to receive focus state, list items must either use a focusable element such as
<a>
, or have an explicittabindex
attribute value.
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">
Two-line item
<span class="mdc-list-item__secondary-text">Secondary text</span>
</span>
</li>
</ul>
As mentioned in the spec, list items (rows) can contain primary and secondary actions. They can also contain things such as avatars, icons, interactive controls, etc. We call all of these items tiles. Lists items can contain 1 supporting graphic tile and/or 1 metadata tile that are positioned at the start and end of the list item, respectively. These tiles are correctly flipped in RTL contexts.
N.B. Please keep accessibility in mind when using things such as icons / icon fonts for tile elements. Font Awesome has excellent guidelines for this.
You can add a supporting graphic using an element with class mdc-list-item__graphic
class.
<ul class="mdc-list">
<li class="mdc-list-item">
<i class="mdc-list-item__graphic material-icons" aria-hidden="true">network_wifi</i>
Wi-Fi
</li>
<li class="mdc-list-item">
<i class="mdc-list-item__graphic material-icons" aria-hidden="true">bluetooth</i>
Bluetooth
</li>
<li class="mdc-list-item">
<i class="mdc-list-item__graphic 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 graphic elements as what
the spec calls "avatars" - large, circular tiles 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__graphic" src="/users/1/profile_pic.png"
width="56" height="56" alt="Picture of Janet Perkins">
Janet Perkins
</li>
<li class="mdc-list-item">
<img class="mdc-list-item__graphic" src="/users/2/profile_pic.png"
width="56" height="56" alt="Picture of Mary Johnson">
Mary Johnson
</li>
<li class="mdc-list-item">
<img class="mdc-list-item__graphic" src="/users/3/profile_pic.png"
width="56" height="56" alt="Picture of Peter Carlsson">
Peter Carlsson
</li>
</ul>
Metadata tiles can be added in a similar way to graphics. Place an element after the text
with a mdc-list-item__meta
class.
<h2>Contacts</h2>
<ul class="mdc-list">
<li class="mdc-list-item">
Janet Perkins
<a href="#" class="mdc-list-item__meta 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__meta 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__meta material-icons"
aria-label="Add to favorites" title="Add to favorites">
favorite_border
</a>
</li>
</ul>
Supporting graphics and metadata can be combined easily. Check out the list demo for many examples of how tiles can be configured.
NOTE: If using controls such as a switch within a list tile, you may need to override the width and height styles set on the tile 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 each list item. Note that this can be easily done
via mdc-auto-init
when using 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__graphic" 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__graphic" 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__graphic" aria-hidden="true">
data_usage
</i>
Data Usage
</a>
</nav>
<script>
mdc.autoInit();
</script>
MDC List contains an mdc-list-divider
class which can be used as full-width or inset
subdivisions either within lists themselves, or 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 thatseparator
is indeed a valid role forli
elements.
Dividers are designed to span the full width of the list by default (especially useful in the context of drawers and menus).
To make a divider match the padding of list items, add the mdc-list-divider--padded
modifier class.
Inset dividers are useful when working with lists which have graphics.
To add an inset divider, also add the mdc-list-divider--inset
modifier class to the divider element.
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 the supporting graphic or metadata 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 tiles you'd like
styled this way. For example, given a timestamp
class for metadata:
.mdc-list-item__meta.timestamp {
/* Lock to top of container. */
align-self: flex-start;
}
Alternatively, if you have multiple items you'd like to put into a tile, you can give it display: flex
and
flex-direction: column
. This will allow you to stack items within a tile, 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. Your 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">
Ali Connors
<span class="mdc-list-item__secondary-text">Lunch this afternoon? I was...</span>
</span>
<span class="mdc-list-item__meta">
<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__meta {
width: auto;
height: auto;
display: inline-flex;
flex-direction: column;
align-items: flex-end;
}
CSS Class | Description |
---|---|
mdc-list | A container for rows (mdc-list-item s) |
mdc-list-group | Wraps one or more mdc-list and/or mdc-list-divider elements |
mdc-list-item | An individual row in an mdc-list |
mdc-list-divider | Separates two rows or two lists using a horizontal bar |
CSS Class | Description |
---|---|
mdc-list--dense | Increases the density of the list, making it appear more compact |
mdc-list--avatar-list | Configures the leading tiles of each row to display images instead of icons |
mdc-list--two-line | Increases the height of the row to give it greater visual separation from adjacent rows |
mdc-list-item--selected | Styles the row in a selected* state |
mdc-list-item--activated | Styles the row in an activated* state |
mdc-list-divider--inset | Increases the leading margin of the divider so that it does not intersect the avatar column |
* Note: the difference between selected and activated states:
CSS Class | Description |
---|---|
mdc-list-item__graphic | The first tile in the row (in LTR languages, the left-most) |
mdc-list-item__meta | The last tile in the row (in LTR languages, the right-most) |
mdc-list-item__text | Primary text for the row (displayed as the middle tile) |
mdc-list-item__secondary-text | Secondary text for the row (displayed in the middle tile) |
mdc-list-group__subheader | Heading text displayed above each list in a group |
Mixin | Description |
---|---|
mdc-list-item-primary-text-ink-color($color) | Sets the ink color of the primary text |
mdc-list-item-secondary-text-ink-color($color) | Sets the ink color of the secondary text |
mdc-list-item-graphic-fill-color($color) | Sets the fill color of the supporting graphic |
mdc-list-item-graphic-ink-color($color) | Sets the ink color of the supporting graphic |
mdc-list-item-meta-ink-color($color) | Sets the ink color of the metadata element |
mdc-list-divider-color($color) | Sets the color of the divider |
mdc-list-group-subheader-ink-color($color) | Sets the ink color of the list group subheader |
FAQs
The Material Components for the web list component
The npm package @material/list receives a total of 699,221 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
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.