@material/react-list

React List

A React version of an MDC List.

Installation

npm install @material/react-list

Usage

Styles

with Sass:

import '@material/react-list/index.scss';

with CSS:

import '@material/react-list/dist/list.css';

Javascript Instantiation

import React, {Component} from 'react';
import List, {ListItem, ListItemText} from '@material/react-list';

class MyApp extends Component {
  render() {
    return (
      <List>
        <ListItem>
          <ListItemText primaryText='Photos'/>
        </ListItem>
        <ListItem>
          <ListItemText primaryText='Recipes'/>
        </ListItem>
        <ListItem>
          <ListItemText primaryText='Work'/>
        </ListItem>
      </List>
    );
  }
}

NOTE: Please use the ListItem component to specify list items. List will not recognize custom list item components.

Also, you can override the element that the List or ListItem renders by passing in a tag prop. By default, List renders a ul and ListItem renders an li. For semantic HTML and a11y, as well as working with routing libraries such as React Router and Next.js' Link, you may wish to use nav and a respectively if using the components to render a page's navigation.

Variants

Two-Line List

You can use the twoLine Boolean prop for List combined with the secondaryText prop for ListItem to style a list as a double line list.

import React, {Component} from 'react';
import List, {ListItem, ListItemText} from '@material/react-list';

class MyApp extends Component {
  render() {
    return (
      <List twoLine>
        <ListItem>
          <ListItemText
            primaryText='Photos'
            secondaryText='Jan 9, 2018' />
        </ListItem>
        <ListItem>
          <ListItemText
            primaryText='Recipes'
            secondaryText='Jan 17, 2018' />
        </ListItem>
        <ListItem>
          <ListItemText
            primaryText='Work'
            secondaryText='Jan 28, 2018' />
        </ListItem>
      </List>
    );
  }
}

List item supporting visuals and metadata

You may add a leading visuals or trailing metadata to a list item using ListItemGraphic before or ListItemMeta after ListItemText.

import React, {Component} from 'react';
import MaterialIcon from '@material/react-material-icon';
import List, {ListItem, ListItemGraphic, ListItemText, ListItemMeta} from '@material/react-list';

class MyApp extends Component {
  render() {
    return (
      <List>
        <ListItem>
          <ListItemGraphic graphic={<MaterialIcon icon='folder'/>} />
          <ListItemText primaryText='Photos' />
          <ListItemMeta meta='info' />
        </ListItem>
        ...
      </List>
    );
  }
}

List groups and list dividers

Multiple related lists can be grouped together using the ListGroup component. Optional subheaders can be added using ListGroupSubheader. ListDividers can be used to separate content either within a list or between lists.

import React, {Component} from 'react';
import List, {
  ListItem, ListItemText, ListGroup, 
  ListGroupSubheader,ListDivider
} from '@material/react-list';

class MyApp extends Component {
  render() {
    return (
      <ListGroup>
        <ListGroupSubheader tag='h2'>Folders</ListGroupSubheader>
        <List>
          <ListItem>
            <ListItemText primaryText='Photos' />
          </ListItem>
          ...
        </List>
        <ListDivider />
        <ListGroupSubheader tag='h2'>Recent Files</ListGroupSubheader>
        <List>
          <ListItem>
            <ListItemText primaryText='Vacation' />
          </ListItem>
          ...
        </List>
      </ListGroup>
    );
  }
}

Single Selection

You can use the singleSelection Boolean prop for List to allow for selection of list items. You can also set the selectedIndex of the list programmatically and include a handleSelect callback.

NOTE: If you are inserting or removing list items, you must update the selectedIndex accordingly.

import React, {Component} from 'react';
import List, {ListItem, ListItemText} from '@material/react-list';

class MyApp extends Component {
  state = {
    selectedIndex: 1,
  };

  render() {
    return (
      <List
        singleSelection
        selectedIndex={this.state.selectedIndex}
        handleSelect={(selectedIndex) => this.setState({selectedIndex})}
      >
        <ListItem>
          <ListItemText primaryText='Photos'/>
        </ListItem>
        <ListItem>
          <ListItemText primaryText='Recipes'/>
        </ListItem>
        <ListItem>
          <ListItemText primaryText='Work'/>
        </ListItem>
      </List>
    );
  }
}

Props

List

Prop Name	Type	Description
className	String	Classes to be applied to the list element
nonInteractive	Boolean	Disables interactivity affordances
dense	Boolean	Styles the density of the list, making it appear more compact
avatarList	Boolean	Configures the leading tiles of each row to display images instead of icons. This will make the graphics of the list items larger
twoLine	Boolean	Styles the list with two lines
singleSelection	Boolean	Allows for single selection of list items
wrapFocus	Boolean	Sets the list to allow the up arrow on the first element to focus the last element of the list and vice versa
selectedIndex	Number	Toggles the selected state of the list item at the given index
handleSelect	Function(selectedIndex: Number) => void	Callback for handling a list item selection event
aria-orientation	String	Indicates the list orientation
tag	String	Customizes the list tag type (defaults to 'ul')

ListItem

Prop Name	Type	Description
className	String	Classes to be applied to the list item element
classNamesFromList	Array	Additional classes to be applied to the list item element, passed down from list
attributesFromList	Array	Additional attributes to be applied to the list item element, passed down from list
childrenTabIndex	Number	Tab index to be applied to all children of the list item
shouldFocus	Boolean	Whether to focus the list item
shouldFollowHref	Boolean	Whether to follow the link indicated by the list item
shouldToggleCheckbox	Boolean	Whether to toggle the checkbox on the list item
onClick	Function(evt: Event) => void	Callback for handling a click event
onKeyDown	Function(evt: Event) => void	Callback for handling a keydown event
onFocus	Function(evt: Event) => void	Callback for handling a focus event
onBlur	Function(evt: Event) => void	Callback for handling a blur event
tag	String	Customizes the list tag type (defaults to 'li')

ListItemText

Prop Name	Type	Description
className	String	Classes to be applied to the list item text element
tabIndex	Number	Tab index of the list item text
tabbableOnListItemFocus	Boolean	Whether focusing list item will toggle tab index of the list item text. If false, the tab index will always be -1
primaryText	String	Primary text for the list item
secondaryText	String	Secondary text for the list item

ListItemGraphic

Prop Name	Type	Description
className	String	Classes to be applied to the list item graphic element
tabIndex	Number	Tab index of the list item graphic
tabbableOnListItemFocus	Boolean	Whether focusing list item will toggle tab index of the list item graphic. If false, the tab index will always be -1
graphic	Element	The graphic element to be displayed in front of list item text

ListItemMeta

Prop Name	Type	Description
className	String	Classes to be applied to the list item meta element
tabIndex	Number	Tab index of the list item meta
tabbableOnListItemFocus	Boolean	Whether focusing list item will toggle tab index of the list item meta. If false, the tab index will always be -1
meta	Element or String	The meta element or string to be displayed behind list item text

ListDivider

Prop Name	Type	Description
className	String	Classes to be applied to the list divider
tag	String	Element tag of the list divider, defaults to li
role	String	ARIA role of the list divider, defaults to separator

ListGroup

Prop Name	Type	Description
className	String	Classes to be applied to the list group
tag	String	Element tag of the list group, defaults to div

ListGroupSubheader

Prop Name	Type	Description
className	String	Classes to be applied to the list group subheader
tag	String	Element tag of the list group subheader, defaults to h3

Sass Mixins

Sass mixins may be available to customize various aspects of the Components. Please refer to the MDC Web repository for more information on what mixins are available, and how to use them.

Advanced Sass Mixins

Changelog

0.8.0 (2018-12-28)

Bug Fixes

• infrastructure: add declaration package.json (#572) (8cb4b1b)
• infrastructure: condense webpack configuration build step into one json file (#571) (512f3aa)
• infrastructure: unit test code coverage for typescript (#487) (1170a1f)
• list: minification-safe element type comparison (#509) (89f5fd2)
• select: defensive foundation check before unmounting - also includes radio, checkbox, text-field (#512) (2ee4c80)
• top-app-bar: foundation should be destroyed and reinitialized on variant change (#519) (58cfc6f)
• lint for typings files (#577) (8f971a8)
• remove prop-types from package.json (#576) (7f38952)

Features

• button: typescript (#508) (fee5968)
• card: typescript (#497) (c9665bc)
• checkbox: typescript support (#490) (02775ac)
• chips: typescript support (#493) (764ed40)
• drawer: typescript support (#494) (2a91edd)
• fab: typescript support (#495) (b62c36f)
• icon-button: typescript support (#496) (e9e29a3)
• infrastructure: add typescript eslint (#549) (abee1a8)
• infrastructure: build JS from TS (#547) (862c110)
• layout-grid: typescript (#498) (a25039e)
• linear-progress: typescript (#526) (cffefa0)
• list: typescript (#501) (3b6c501)
• material-icon: typescript (#525) (e3373bb)
• menu-surface: typescript (#502) (94d006d)
• radio: typescript (#506) (af94a3a)
• ripple: typescript (#527) (4dcf389)
• select: typescript (#540) (a3d014a)
• switch: typescript (#530) (ba058d4)
• tab: typescript (#532) (206540f)
• tab-bar: typescript (#535) (a0709d7)
• tab-indicator: typescript (#545) (056adb5)
• tab-scroller: typescript (#536) (4582a7d)
• text-field: add typescript support (#550) (e003fea)
• top app bar: dense variant (#520) (461cce9)
• top-app-bar: TopAppBarFixedAdjust variants added (#524) (e3bb701)
• top-app-bar: typescript (#548) (8680796)
• typography: typescript (#521) (090aa7e)

BREAKING CHANGES

• infrastructure: Remove <package-name>.es.js files. The alternate is now to use the index.tsx files.
• ripple: withRipple is no longer the default export.

<a name="0.7.1"></a>