Lists

Lists are continuous, vertical indexes of text or images.

Interactive demo

This demo lets you preview the list component, its variations, and configuration options. Each tab displays a different type of list.

Usage

Lists are a continuous group of text or images. They are composed of items containing primary and supplemental actions, which are represented by icons and text.

Principles

Logical

Lists should be sorted in logical ways that make content easy to scan, such as alphabetical, numerical, chronological, or by user preference.

Actionable

Lists present content in a way that makes it easy to identify a specific item in a collection and act on it.

Consistent

Lists should present icons, text, and actions in a consistent format.

Types

Single-line list items contain a maximum of one line of text. Two-line list items contain a maximum of two lines of text. Three-line list items...

**1. Single-line list**
Single-line list items contain a maximum of one line of text.

**2. Two-line list**
Two-line list items contain a maximum of two lines of text.

**3. Three-line list**
Three-line list items contains a maximum of three lines of text.

Anatomy

Lists are optimized for reading comprehension. A list consists of a single continuous column of subdivisions called rows that contain items of content.

Content types

Content types can take different forms, depending on the needs of a list. A list control can display information and actions for list items. A...

Content types can take different forms, depending on the needs of a list.

List items are comprised of three different content types:

1. Supporting visuals
2. Primary text
3. Metadata

A list control can display information and actions for list items.

Lists with controls contain three content types:

1. Supporting visuals
2. Primary text
3. List control

A list should be easily scannable, and any element of a list can be used to anchor and align list item content. Scannability is improved when elements (such as supporting visual and primary text) are placed in consistent locations across list items.

1. Sample list
2. Content placement in a row
3. Supporting visuals are aligned for easy scanning
4. Primary text is aligned for easy scanning

Visuals, dividers, and spacing

The structure of a list can be clarified using visuals, dividers, and spacing

List structure can be organized using visuals, dividers, and spacing.

DoImprove scannability by anchoring supporting visuals, such as thumbnails, along the row's edge.

CautionPlacing supporting visuals in the center of the row can make it difficult to see the relationship between primary content and supporting content.

DoPlace a divider between rows with lots of content, such as those with three-line lists.

CautionDistinguish rows by maintaining sufficient space between list items.

The primary action takes up the majority of space.
1. Primary Action area
2. Secondary Action area

Clear hierarchy is created by aligning the most distinguishing content on the left, with the least distinguishing on the right.
1. More distinguishing content
2. Less distinguishing content

Subheaders

Subheaders delineate sections of a list

Subheaders delineate sections of a list. They appear on list rows.

**1. Subheader**
A subheader should be left-aligned with an avatar or icon in a list.

**2. Subheader inset**
If a floating action button is aligned with list avatars or icons, the subheader should be aligned with the text content.

Behavior

Transitions

Tapping a list item expands it across the entire screen. Navigational transitions are movements between states in an app, such as from a high-level view...

Tapping a list item expands it across the entire screen using a container transform transition pattern.

To expand a list item, display a parent-child transition.

Gestures

Swiping a list item (either left or right) can perform an action. Items can be dragged to reorder a list.

Swiping a list item (either left or right) can perform an action.

To archive a list item, swipe it.

Items can be dragged to reorder a list.

To reorder a list item, drag it.

Expand

A three-line list transition (on mobile) is displayed as a two-line list (on desktop).

Scaled down to 50%
1. A three-line list on mobile
2. A two-line list on desktop

Transform

On a larger screen, a list may transform into an image list.

1. A one-line list on mobile
2. An image list on desktop

Reveal additional content

Lists can also show more or less content as they scale up and down in size.

Lists can also show more or less content as they scale up and down in size. For example, a list item can reveal more content when the component expands.

Diagram of list items on mobile transitioning to wider list items with more text on tablet — List items on larger screens (right) can display more information as the screen size transitions from small to medium breakpoints.

Scaling and adaptation

Line length

Avoid excessively long lines of text when expanding containers and text-heavy components within fluid layouts. This often means changing margins and typography properties as the container scales.

The ideal line length for text is typically between 40-60 characters, but large screen devices can accommodate up to 120 characters per line. Consider increasing the line height to improve readability if a line of text becomes close to 120 characters in length.

Adapt the width of the list container based on a line’s length, or by switching to a multi-column layout.

Example UI where list items have a wide right margin to shorten line lengths — DoAdjust margins to create a more comfortable line length for reading.

List items that take up the full width of the screen — Don'tDon’t scale components without adjusting other affected areas of the screen, such as text length. This can result in line lengths that make reading difficult.

A two-column list centered on a large screen — DoA multi-column layout can help break up content when needed.

Component adaptation

Visual presentation is the most common method of adaptation, affecting the scale and placement of content and objects on a screen, as well as their relationships to each other.

For example, a text list on mobile can adjust its margins, vertical spacing, or density to better fit large screens like tablets.

Component swapping

Given the flexibility needed for lists and cards to support multiple types of content, use caution if swapping between the two on large screens. As screen sizes increase, there are new opportunities for text and image compositions; in large screens you can use more space for images and text.

Example of a list adapting to a larger image list on tablet

Composition

Lists and views

On smaller screens, lists extend edge-to-edge. Users navigate between full-screen views, as seen in a photo app’s transition from a thumbnail list to full image view.

Example UI showing a list navigating into a full-screen image list view on mobile — On small screens, users navigate between full-screen views.

Large screens can display primary and secondary content in the same view, such as a list adjacent to a detail view.

Example of a list/detail UI — On larger screens, a list/detail view can be more appropriate.

Types

Single-line list

Scaled down to 50% on desktop, a single-line list with icons and text.

Two-line list

In a two-line list, each row contains two lines of text maximum.

A two-line list, with a thumbnail and meta text.

The amount of text can vary between different rows within the same list.

Scaled down to 50% on desktop, a two-line list accompanied by an avatar and meta text.

Three-line list

A three-line text list, with a thumbnail and meta text.

The amount of text can vary between rows within the same list.

On desktop, a three-line list accompanied by a large thumbnail and meta text.

List controls

List controls display information and actions for list items. A checkbox can either be a primary or secondary action. Show and hide details of existing...

List controls display information and actions for list items.

Checkbox

A checkbox can either be a primary or secondary action.

Expand and collapse

Show and hide details of existing list items by expanding and collapsing list content vertically.

Tapping the list control expands the list.

Switch

Reorder

Theming

Basil Material theme

This recipe app's lists have been customized using Material Theming. Areas of customization include color and typography. Basil is a recipe app that uses Material...

This recipe app's lists have been customized using Material Theming. Areas of customization include color and typography.

Color

Basil's lists use custom color on four elements: the background, icon, item text, and quantity text.

Element	Category	Attribute	Value
Surface	Surface	Color Opacity	#FFFBE6 100%
Item text, Icons	Primary	Color Opacity	#356859 100%
Quantity text	On Surface	Color Opacity	#29302E 100%

Typography

Basil's lists use custom typography for item and quantity text.

Element	Category	Attribute	Value
Item text	Subtitle 1	Typeface Font Size Case	Lekton Bold 16 Title case
Quantity text	Caption	Typeface Font Size Case	Lekton Regular 12 Sentence case

Crane Material theme

This travel app's lists have been customized using Material Theming. Areas of customization include color and typography. Crane is a travel app that uses Material...

This travel app's lists have been customized using Material Theming. Areas of customization include color and typography.

Typography

Crane's lists use custom typography for title and caption text.

Element	Category	Attribute	Value
Title text	Subtitle 1	Typeface Font Size Case	Raleway Medium 16 Title case
Caption text	Caption	Typeface Font Size Case	Raleway SemiBold 12 Title case

Specs

One line

Measurement 56
Measurement 56
Measurement 56
Measurement 8
Measurement 8

Measurement 56
Measurement 56
Measurement 56
Measurement 56

Two line

Measurement 64
Measurement 64
Measurement 72
Measurement 72
Measurement 72
Measurement 72
Measurement 16
Measurement 16
Measurement 24
Measurement 28
Measurement 16
Measurement 16
Measurement 16
Measurement 32
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 8
Measurement 28
Measurement 20
Measurement 20
Measurement 24
Measurement 32
Measurement 20
Measurement 32
Measurement 20
Measurement 32
Measurement 24
Measurement 20
Measurement 24
Measurement 32
Measurement 20
2424
4040
4040
10056
2424
2424
2424

Measurement 8
Measurement 8
Measurement 72
Measurement 72
Measurement 72

Three line

Measurement 16
Measurement 16
Measurement 88
Measurement 88
Measurement 88
Measurement 88
Measurement 88
Measurement 88
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 16
Measurement 32
Measurement 16
Measurement 20
Measurement 16
Measurement 16
Measurement 16
Measurement 20
Measurement 28
Measurement 28
Measurement 20
Measurement 28
Measurement 20
Measurement 28
Measurement 20
Measurement 28
Measurement 20
Measurement 16
Measurement 16
Measurement 16
Measurement 236
Measurement 28
Measurement 20
2424
4040
10056
2424
4040

The trailing padding (padding to the right of the image) in the example above and below is intended to be 16dp.

Measurement 88
Measurement 88
Measurement 88
Measurement 8
Measurement 8

Collapsed & expanded

All measurements are displayed in device-independent pixels (dps)

Measurement 48
Measurement 48
Measurement 48
Measurement 48
Measurement 72
Measurement 16
Measurement 32
2424

Demo

Lists are under development. You can see the current version of the Lists Demo in the Material Android Catalog.

Code

The Lists Package contains the code for this component.

No Android implementation guidance available

Using lists

Installation

xxxxxxxxxx

Styles

xxxxxxxxxx

JavaScript

MDC List includes an optional JavaScript component which can be used for keyboard interaction and accessibility.

xxxxxxxxxx

See Importing the JS component for more information on how to import JavaScript.

Note that the JS component does not automatically instantiate ripples on list items. If you wish to include the fully-upgraded ripple effect on list items, you must instantiate MDCRipple on each item:

xxxxxxxxxx

Making lists accessible

The MDCList JavaScript component implements the WAI-ARIA best practices for listbox. This includes overriding the default tab behavior within the list component.

The tabindex should be set to 0 for first list item element or selected list item element, remaining list item elements should not have tabindex set.

Use role="listbox" only for single selection list, without this role the ul element is implicitely role="list". Do not use aria-orientation attribute for standard list (i.e., role="list"), use component's vertical property to set the orientation to vertical.

Single selection list supports aria-selected and aria-current attributes. List automatically detects the presence of these attributes and sets it to next selected list item based on which ARIA attribute you use (i.e., aria-selected or aria-current). Please see WAI-ARIA aria-current article for recommended usage and available attribute values.

As the user navigates through the list, any button and a elements within the list will receive tabindex="-1" when the list item is not focused. When the list item receives focus, the aforementioned elements will receive tabIndex="0". This allows for the user to tab through list item elements and then tab to the first element after the list. The Arrow, Home, and End keys should be used for navigating internal list elements. If singleSelection=true, the list will allow the user to use the Space or Enter keys to select or deselect a list item. The MDCList will perform the following actions for each key press. Since list interaction will toggle a radio button or checkbox within the list item, the list will not toggle tabindex for those elements.

Disabled list item will be included in the keyboard navigation. Please see Focusability of disabled controls section in ARIA practices article.

Key	Action
ArrowUp	When the list is in a vertical orientation (default), it will cause the previous list item to receive focus.
ArrowDown	When the list is in a vertical orientation (default), it will cause the next list item to receive focus.
ArrowLeft	When the list is in a horizontal orientation, it will cause the previous list item to receive focus.
ArrowRight	When the list is in a horizontal orientation, it will cause the next list item to receive focus.
Home	Will cause the first list item in the list to receive focus.
End	Will cause the last list item in the list to receive focus.
Space	Will cause the currently focused list item to become selected/deselected if singleSelection=true.
Enter	Will cause the currently focused list item to become selected/deselected if singleSelection=true.

Single-line list

Single-line list items contain a maximum of one line of text.

Single-line list example

xxxxxxxxxx

Two-line list

Two-line list items contain a maximum of two lines of text.

Two-line list example

Use the mdc-list--two-line combined with some extra markup around the text to style a two-line list.

xxxxxxxxxx

Note: Make sure there are no white-space characters before primary and secondary text content.

Three-line list

Three-line list items contains a maximum of three lines of text.

MDC Web does not currently support three-line lists.

Other Variants

List Groups

Multiple related lists can be grouped together using the mdc-list-group class on a containing element.

xxxxxxxxxx

List Dividers

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.

xxxxxxxxxx

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 that separator is indeed a valid role for li elements.

xxxxxxxxxx

Single Selection List

MDC List can handle selecting/deselecting list elements based on click or keyboard actions. When enabled, the space and enter keys (or click event) will trigger a single list item to become selected and any other previously selected element to become deselected.

xxxxxxxxxx

xxxxxxxxxx

Pre-selected list item

When rendering the list with a pre-selected list item, the list item that needs to be selected should contain the mdc-list-item--selected or mdc-list-item--activated class before creating the list. Please see Accessibility section for appropriate aria attributes.

xxxxxxxxxx

xxxxxxxxxx

List with radio group

When rendering list radio group with pre-selected radio button the selected list item should contain aria-checked set to true and the native radio input element contains checked attribute, all other list items should have aria-checked set to false. The list root contains role="radiogroup" whereas each list item within radio group contains role="radio".

xxxxxxxxxx

List with checkbox items

When rendering list with checkbox items all pre-selected list items should contain aria-checked set to true and the native checkbox input element should contain checked attribute, all other list items should have aria-checked set to false. Each list item in checkbox list contains role="checkbox" attribute and the list root should contain role="group" and aria-label attributes.

xxxxxxxxxx

The selectedIndex (that proxies foundation's setSelectedState()) accepts list of indexes in array format for list with checkbox items to set the selection state. It overwrites the current state with new selected state.

Style Customization

CSS Classes

CSS Class	Description
mdc-list	Mandatory, for the list element.
mdc-list--dense	Optional, styles the density of the list, making it appear more compact.
mdc-list--textual-list	Optional, configures lists that start with text
(e.g., do not have a leading tile).
mdc-list--avatar-list	Optional, configures the leading tile of each row to
display avatars.
mdc-list--icon-list	Optional, configures the leading tile of each row to
display icons.
mdc-list--image-list	Optional, configures the leading tile of each row to
display images.
mdc-list--thumbnail-list	Optional, configures the leading tile of each row to
display smaller images (this is analogous to an avatar list but the image will
not be rounded).
mdc-list--video-list	Optional, configures the leading tile of each row to
display videos.
mdc-list--two-line	Optional, modifier to style list with two lines (primary and secondary lines).
mdc-list-item	Mandatory, for the list item element.
mdc-list-item__text	Mandatory. Wrapper for list item text content (displayed as middle column of the list item).
mdc-list-item__primary-text	Optional, primary text for the list item. Should be the child of mdc-list-item__text.
mdc-list-item__secondary-text	Optional, secondary text for the list item. Displayed below the primary text. Should be the child of mdc-list-item__text.
mdc-list-item--disabled	Optional, styles the row in the disabled state.
mdc-list-item--selected	Optional, styles the row in the selected* state.
mdc-list-item--activated	Optional, styles the row in the activated* state.
mdc-list-item__graphic	Optional, the first tile in the row (in LTR
languages, the first column of the list item). Defaults to an icon, but renders
as an avatar in an avatar list, or an image or video in the corresponding list.
mdc-list-item__meta	Optional, the last tile in the row (in LTR languages,
the last column of the list item). Typically small text, icon, or image.
mdc-list-group	Optional, wrapper around two or more mdc-list elements to be grouped together.
mdc-list-group__subheader	Optional, heading text displayed above each list in a group.
mdc-list-divider	Optional, for list divider element.
mdc-list-divider--padded	Optional, leaves gaps on each side of divider to
match padding of list-item__meta. Deprecated: use the more flexible "inset-"
classes, instead.
mdc-list-divider--inset	Optional, increases the leading and trailing margins
of the divider so that it doesn't intersect with an avatar. Deprecated: use the
more flexible "inset-" classes instead.
mdc-list-divider--inset-leading	Optional, increases the leading margin of
the divider so that it does not intersect the graphics column.
mdc-list-divider--inset-trailing	Optional, increases the trailing margin of
the divider so that it coincides with the item's padding.
mdc-list-divider--inset-padding	Optional, alters the inset to correspond to
the item's padding rather than the leading graphics column.

Note: The mdc-list-divider class can be used between list items OR between two lists (see respective examples under List Dividers).

Note: In Material Design, the selected and activated states apply in different, mutually-exclusive situations:

Selected state should be applied on the .mdc-list-item when it is likely to frequently change due to user choice. E.g., selecting one or more photos to share in Google Photos.
Activated state is more permanent than selected state, and will NOT change soon relative to the lifetime of the page. Common examples are navigation components such as the list within a navigation drawer.

Sass Mixins

Mixin	Description
item-primary-text-ink-color($color)	Sets the ink color of the primary text of the list item.
item-secondary-text-ink-color($color)	Sets the ink color of the secondary text of the list item.
item-graphic-fill-color($color)	Sets background ink color of the graphic element within list item.
item-graphic-ink-color($color)	Sets ink color of the graphic element within list item.
item-meta-ink-color($color)	Sets ink color of the meta element within list item.
single-line-shape-radius($radius, $rtl-reflexive, $density-scale)	Sets the rounded shape to list item with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false. Set $density-scale only when custom density is applied, defaults to $mdc-list-single-line-density-scale.
divider-color($color)	Sets divider ink color.
group-subheader-ink-color($color)	Sets ink color of subheader text within list group.
item-selected-text-color($color)	Sets the color of the text when the list item is selected/activated.
item-disabled-text-color($color)	Sets the color of the text when the list item is disabled.
item-disabled-text-opacity($opacity)	Sets the opacity of the text when the list item is disabled.
single-line-density($density-scale)	Sets density scale to single line list variant. Supported density scales are -4, -3, -2, -1 and 0.
single-line-height($height)	Sets height to single line list variant.
list-item-padding($leading-padding)	Sets the padding used by each list item.
list-item-height($height)	Sets the height used by each list item.
icon-margin($margin)	Sets the trailing margin used by icons.
divider-insets($leading-padding, $text-offset)	Creates the full set of
divider inset styles using the provided padding and text offset.
divider-insets($leading-padding, $text-offset)	Sets a single divider's inset
using the provided padding, text offset, and configuration.
graphic-size($leading-padding, $text-offset, $width, $height)	Sets the size
and trailing margin of a leading graphic.

MDCList Properties and Methods

Property	Value Type	Description
vertical	boolean (write-only)	Proxies to the foundation's setVerticalOrientation() method.
listElements	Array<Element> (read-only)	Returns all list item elements including disabled list items.
wrapFocus	boolean (write-only)	Proxies to the foundation's setWrapFocus() method.
typeaheadInProgress	boolean (read-only)	Proxies to foundation's isTypeaheadInProgress method.
hasTypeahead	boolean (write-only)	Proxies to the foundation's setHasTypeahead() method.
singleSelection	boolean (write-only)	Proxies to the foundation's setSingleSelection() method.
selectedIndex	MDCListIndex	Proxies to the foundation's getSelectedIndex() and setSelectedIndex() methods.

Method Signature	Description
layout() => void	Recalculates layout and orientation.
getPrimaryText(item: Element) => string	Fetches the primary text in the given element.
initializeListType() => void	Initialize selectedIndex value based on pre-selected checkbox list items, single selection or radio.
setEnabled(itemIndex: number, isEnabled: boolean) => void	Updates the list item at itemIndex to the desired isEnabled state.

Events

Event Name	event.detail	Description
MDCList:action	{index: number}	Indicates that a list item with the specified index has been activated.

Usage within Web Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a List for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

Considerations for Advanced Approach

The MDCListFoundation expects the HTML to be setup a certain way before being used. This setup is a part of the layout() and singleSelection() functions within the index.js.

Setup in layout()

The default component requires that every list item receives a tabindex value so that it can receive focus (li elements cannot receive focus at all without a tabindex value). Any element not already containing a tabindex attribute will receive tabindex=-1. The first list item should have tabindex="0" so that the user can find the first element using the tab key, but subsequent tab keys strokes will cause focus to skip over the entire list. If the list items contain sub-elements that are focusable (button and a elements), these should also receive tabIndex="-1".

xxxxxxxxxx

Setup in singleSelection()

When implementing a component that will use the single selection variant, the HTML should be modified to include the mdc-list-item--selected or mdc-list-item--activated class name, and the tabindex of the selected element should be 0. The first list item should have the tabindex updated to -1. The foundation method setSelectedIndex() should be called with the initially selected element immediately after the foundation is instantiated. Please see Accessibility section for appropriate aria attributes.

xxxxxxxxxx

MDCListAdapter

Method Signature	Description
getListItemCount() => Number	Returns the total number of list items (elements with mdc-list-item class) that are direct children of the root_ element.
getFocusedElementIndex() => Number	Returns the index value of the currently focused element.
`getAttributeForElementIndex(index: number, attribute: string) => string	null`
setAttributeForElementIndex(index: Number, attr: String, value: String) => void	Sets the attr attribute to value for the list item at index.
addClassForElementIndex(index: Number, className: String) => void	Adds the className class to the list item at index.
removeClassForElementIndex(index: Number, className: String) => void	Removes the className class to the list item at index.
focusItemAtIndex(index: Number) => void	Focuses the list item at the index value specified.
setTabIndexForListItemChildren(index: Number, value: Number) => void	Sets the tabindex attribute to value for each child button or anchor element in the list item at the index specified.
hasRadioAtIndex(index: number) => boolean	Returns true if radio button is present at given list item index.
hasCheckboxAtIndex(index: number) => boolean	Returns true if checkbox is present at given list item index.
isCheckboxCheckedAtIndex(index: number) => boolean	Returns true if checkbox inside a list item is checked.
setCheckedCheckboxOrRadioAtIndex(index: number, isChecked: boolean) => void	Sets the checked status of checkbox or radio at given list item index.
notifyAction(index: number) => void	Notifies user action on list item including keyboard and mouse actions.
isFocusInsideList() => boolean	Returns true if the current focused element is inside list root.
isRootFocused() => boolean	Returns true if root element is focused.
listItemAtIndexHasClass(index: number, className: string) => boolean	Returns true if list item at index has class className.
getPrimaryTextAtIndex(index: number)	Returns the primary text content of the list item at index.

MDCListFoundation

Method Signature	Description
setWrapFocus(value: Boolean) => void	Sets the list to allow the up arrow on the first element to focus the last element of the list and vice versa.
setVerticalOrientation(value: Boolean) => void	Sets the list to an orientation causing the keys used for navigation to change. true results in the Up/Down arrow keys being used. false results in the Left/Right arrow keys being used.
setSingleSelection(value: Boolean) => void	Sets the list to be a selection list. Enables the enter and space keys for selecting/deselecting a list item.
getSelectedIndex() => MDCListIndex	Gets the current selection state by returning selected index or list of indexes for checkbox based list. See types.ts for MDCListIndex type definition.
setSelectedIndex(index: MDCListIndex) => void	Sets the selection state to given index or list of indexes if it is checkbox based list. See types.ts for MDCListIndex type definition.
setUseActivatedClass(useActivated: boolean) => void	Sets the selection logic to apply/remove the mdc-list-item--activated class.
handleFocusIn(evt: Event) => void	Handles the changing of tabindex to 0 for all button and anchor elements when a list item receives focus.
handleFocusOut(evt: Event) => void	Handles the changing of tabindex to -1 for all button and anchor elements when a list item loses focus.
handleKeydown(evt: Event) => void	Handles determining if a focus action should occur when a key event is triggered.
handleClick(evt: Event) => void	Handles toggling the selected/deselected state for a list item when clicked. This method is only used by the single selection list.
focusNextElement(index: number) => number	Handles focusing the next element using the current index. Returns focused element index.
focusPrevElement(index: number) => number	Handles focusing the previous element using the current index. Returns focused element index.
focusFirstElement() => number	Handles focusing the first element in a list. Returns focused element index.
focusLastElement() => number	Handles focusing the last element in a list. Returns focused element index.
setEnabled(itemIndex: number, isEnabled: Boolean) => void	Updates the list item's disabled state.
setHasTypeahead(hasTypeahead: Boolean) => void	Sets whether typeahead is enabled on the list.
isTypeaheadInProgress() => Boolean	Returns whether typeahead is currently matching a user-specified prefix.
typeaheadMatchItem(nextChar: string) => number	Adds a character to the typeahead buffer and returns index of the next item in the list matching the buffer.
clearTypeaheadBuffer() => void	Clears the typeahead buffer.

No Web implementation guidance available

Using lists

Making lists accessible

Flutter's list component APIs support labeling for accessibility. For more guidance on writing labels, go to our page on how to write a good accessibility label.

List anatomy

The following anatomy diagram applies to all three list types:

The following anatomy diagrams apply to the list item content:

List item content showing supporting visuals, primary text, metadata, and controls in two list components

A list consists of the following attributes:

List
Row
List item content
1. Supporting visuals
2. Primary text
3. Metadata
4. Controls

Types

There are three list types:

Single-line list

Single-line list items contain a maximum of one line of text.

Single-line list example

Source code API: ListTile

xxxxxxxxxx

Single-line list key properties

List
Row
List item
Supporting visuals
Primary text
Metadata

List properties for single line list

	Property
Padding around the list	padding on ListView

Row properties for single line list

	Property
Enabled row	enabled on ListTile
Selected row	selected on ListTile
Padding on rows	padding on ListTile

List item content for single line list

The following are tables of the list item contents:

Supporting visuals for single line list

	Property
Icon	leading on ListTile

Primary text for single line list

	Property
Text label	title on ListTile
Text color	Within title property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within title property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Metadata for single line list

	Property
Text label	trailing on ListTile
Text color	Within trailing property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within trailing property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Controls for single line list

	Property
Primary action	Add interactive widget to leading on ListTile
Secondary action	Add interactive widget to trailing on ListTile

Two-line list

Two-line list items contain a maximum of two lines of text.

Two-line list example

Source code API: ListTile

xxxxxxxxxx

Two-line list key properties

The following are tables of the list item contents:

List item content for two line list

The following are tables of the list item contents:

Supporting visuals
Primary text
Secondary text
Metadata
Controls

Supporting visuals for two line list

	Property
Icon	leading on ListTile

Primary text for two line list

	Property
Text label	title on ListTile
Text color	Within title property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within title property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Secondary text for two line list

	Property
Text label	subtitle on ListTile
Text color	Within subtitle property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within subtitle property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Metadata for two line list

	Property
Text label	trailing on ListTile
Text color	Within trailing property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within trailing property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Controls for two line list

	Property
Primary action	Add interactive widget to leading on ListTile
Secondary action	Add interactive widget to trailing on ListTile

Three-line list

Three-line list items contains a maximum of three lines of text.

Three-line list example

Source code API: ListTile

xxxxxxxxxx

Three-line list key properties

The following are tables of the list item contents:

Supporting visuals
Primary text
Secondary text
Tertiary text
Metadata
Controls

Supporting visuals for three line list

	Property
Icon	leading on ListTile

Primary text for three line list

	Property
Text label	title on ListTile
Text color	Within title property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within title property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Secondary text for three line list

	Property
Text label	subtitle on ListTile
Text color	Within subtitle property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within subtitle property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Tertiary text for three line list

	Property
Text label	subtitle on ListTile with isThreeLine set to true
Text color	Within subtitle property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within subtitle property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Metadata for three line list

	Property
Text label	trailing on ListTile
Text label	Not by default but can be made by using ListTile() and use property trailing
Text color	Within trailing property you can customize the Text color by using the style property. The style property uses a TextStyle property and within that class use the color property.
Typography	Within trailing property you can customize the typography by using the style property. The style property uses a TextStyle property and within that class use the fontFamily property.

Controls for three line list

	Property
Primary action	Add interactive widget to leading on ListTile
Secondary action	Add interactive widget to trailing on ListTile

Theming lists

Lists support Material Theming and can be customized in terms of color and typography.

Dartpad Demo

xxxxxxxxxx

No Flutter implementation guidance available

Using lists

Installing

In order to install lists with Cocoapods first add the List component subspec to your Podfile:

pod 'MaterialComponents/List'

Then, run the following command:

xxxxxxxxxx
pod install

From there, import the relevant target or file and use your list item like you would any other UICollectionViewCell.

Swift

xxxxxxxxxx
import MaterialComponents.MaterialList

Objective-C

List classes

We currently offer two UICollectionViewCell subclasses that can be used to create Material Design lists: MDCBaseCell and MDCSelfSizingStereoCell.

MDCBaseCell

The MDCBaseCell is a list item in its simplest form, a UICollectionViewCell subclass with ripple and elevation. The MDCBaseCell provides a starting point to build anything demonstrated in the extensive design guidelines. To build a list using MDCBaseCell simply treat it like you would any other UICollectionViewCell.

MDCSelfSizingStereoCell

The MDCSelfSizingStereoCell is a subclass of MDCBaseCell. It exposes two image views (trailing and leading) and two labels (title and detail) that the user can configure however they like.

Animation showing a list of stereo cell scrolling up and down

Because the list items we provide inherit from UICollectionViewCell, clients are not expected to instantiate them themselves. Rather, clients should register the cell classes with UICollectionViews, and then cast the cells to the correct class in their implementations of -collectionView:cellForItemAtIndexPath:.

Swift

​x
// registering the cellcollectionView.register(MDCBaseCell.self, forCellWithReuseIdentifier: "baseCellIdentifier")​// casting the cell to the desired type within `-collectionView:cellForItemAtIndexPath:`guard let cell = collectionView.cellForItem(at: indexPath) as? MDCBaseCell else { fatalError() }

Objective-C

Making lists accessible

Setting -isAccessibilityElement

We recommend setting UICollectionViewCells (and UITableViewCells) as accessibilityElements. That way, VoiceOver doesn't traverse the entire cell and articulate an overwhelming amount of accessibility information for each of its subviews.

Swift

xxxxxxxxxx
cell.isAccessibilityElement = true

Objective-C

List anatomy

The following is an anatomy diagram of a typical list that applies to single-line, two-line, and three-line lists:

This list item consists of the following attributes:

Leading image view
Title label and detail label
Trailing label

NOTE: MDCSelfSizingStereoCell currently only supports leading and trailing image views, so the trailing label would be represented by a UIImageView.

An instance of MDCSelfSizingStereoCell can be configured to be a single-line, two-line, or three-line list item. The features above map to the following propertieis and methods:

Container attributes

	Attribute	Related methods	Default value
Color	rippleColor	-setRippleColor: -setRippleColor	On surface color at 0.12 opacity
Elevation	elevation	-setElevation: -elevation	0

Icon attributes

	Attribute	Related methods	Default value
Leading image	leadingImageView	N/A	N/A
Trailing image	trailingImageView	N/A	N/A

Text label attributes

	Attribute	Related methods	Default value
Title text	titleLabel	N/A	N/A
Detail text	titleLabel	N/A	N/A

Types

There are three list types: 1. Single-line list, 2. Two-line list 3. Three-line list

Single-line list

Single-line list items contain a maximum of one line of text.

Single-line list example

Image of three single-line list items with sample text

Swift

xxxxxxxxxx
func collectionView(_ collectionView: UICollectionView,                    cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {  guard cell = collectionView.dequeueReusableCell(    withReuseIdentifier: kSelfSizingStereoCellIdentifier,    for: indexPath)    as? MDCCollectionViewTextCell    else { return }  cell.titleLabel.text = "This is a single-line list"  return cell}

Objective-C

Two-line list

Two-line list items contain a maximum of two lines of text.

Two-line list example

Image of three two-line list items with sample text

Swift

xxxxxxxxxx
func collectionView(_ collectionView: UICollectionView,                    cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {  guard cell = collectionView.dequeueReusableCell(    withReuseIdentifier: kSelfSizingStereoCellIdentifier,    for: indexPath)    as? MDCCollectionViewTextCell    else { return }  cell.titleLabel.text = "This is a two-line list"  cell.detailLabel.text = "This is secondary text that occupies one line."  return cell}

Objective-C

Three-line list

Three-line list items contains a maximum of three lines of text.

Three-line list example

Image of three three-line list items with sample text

Swift

xxxxxxxxxx
func collectionView(_ collectionView: UICollectionView,                    cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {  guard cell = collectionView.dequeueReusableCell(    withReuseIdentifier: kSelfSizingStereoCellIdentifier,    for: indexPath)    as? MDCCollectionViewTextCell    else { return }  cell.titleLabel.text = "This is a three-line list"  cell.detailLabel.text = "This is secondary text\nthat occupies two lines."  return cell}

Objective-C

Theming

This is an example of a two-line list with Shrine theming:

To theme a list item in your own app, use the Material Theming extension. To do that, first add the theming extension to your Podfile:

xxxxxxxxxx
pod `MaterialComponents/List+Theming`

Then run the installer:

xxxxxxxxxx
pod install

From there, call the theming method from your UICollectionViewDelegate code.

Swift

xxxxxxxxxx
// Step 1: Import the theming extensionimport MaterialComponents.MaterialList_Theming​// Step 2: Create a shared container scheme. A shared scheme should be created once in your app and// shared with all components.let containerScheme = MDCContainerScheme()​// Step 3: Apply the scheme to each cell - from within `collectionView(_:cellForItemAt:)`cell.applyTheme(withScheme:containerScheme)

Objective-C

Building your own list item

The example files can be found here

Our example consists of a custom UICollectionViewController: examples/CollectionListCellExampleTypicalUse.m and also of a custom UICollectionViewCell: examples/supplemental/CollectionViewListCell.m.

The main focus will be on the custom cell as that's where all the logic goes in, whereas the collection view and its controller are using mostly boilerplate code of setting up a simple example and collection view.

Layout

For our example we will have a layout consisting of a left aligned UIImageView, a title text UILabel and a details text UILabel. The title text will have a max of 1 line whereas the details text can be up to 3 lines. It is important to note that neither the image nor the labels need to be set. To see more of the spec guidelines for Lists please see here: https://material.io/go/design-lists

To create our layout we used auto layout constraints that are all set up in the (void)setupConstraints method in our custom cell. It is important to make sure we set translatesAutoresizingMaskIntoConstraints to NO for all the views we are applying constraints on.

Ink ripple

Interactable Material components and specifically List Cells have an ink ripple when tapped on. To add ink to your cells there are a few steps you need to take:

Add an MDCInkView property to your custom cell.

Initialize MDCInkView on init and add it as a subview:

Swift

xxxxxxxxxx
let inkView = MDCInkView(frame: bounds)inkView.usesLegacyInkRipple = falseaddSubview(inkView)

Objective-C

Initialize a CGPoint property in your cell (CGPoint _lastTouch;) to indicate where the last tap was in the cell.

Override the UIResponder's touchesBegan method in your cell to identify and save where the touches were so we can then start the ripple animation from that point:

Swift

xxxxxxxxxx
override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {  let touch = touches.first  let location = touch?.location(in: self)  lastTouch = location}

Objective-C

Override the setHighlighted method for your cell and apply the start and stop ripple animations:

Swift

xxxxxxxxxx
override var isHighlighted: Bool {  set {    super.isHighlighted = newValue    if (newValue) {      inkView.startTouchBeganAnimation(at: lastTouch, completion: nil)    } else {      inkView.startTouchEndedAnimation(at: lastTouch, completion: nil)    }  }  // get...}

Objective-C

When the cell is reused we must make sure no outstanding ripple animations stay on the cell so we need to clear the ink before:
Swift
xxxxxxxxxx
override func prepareForReuse() {
inkView.cancelAllAnimations(animated: false)
super.prepareForReuse()
}
Objective-C
xxxxxxxxxx
Now there is ink in our cells!

Self sizing

In order to have cells self-size based on content and not rely on magic number constants to decide how big they should be, we need to follow these steps:

Apply autolayout constraints of our added subviews relative to each other and their superview (the cell's contentView).
We need to make sure our constraints don't define static heights or widths but rather constraints that are relative or our cell won't calculate itself based on the dynamically sized content. You can see how it is achieved in the setupConstraints method in our example. If you'll notice there are some constraints that are set up to be accessible throughout the file:
Swift
xxxxxxxxxx
var imageLeftPaddingConstraint: NSLayoutConstraint
var imageRightPaddingConstraint: NSLayoutConstraint
var imageWidthConstraint: NSLayoutConstraint
Objective-C
xxxxxxxxxx
This is in order to support the changing layout if an image is set or not.
Because our list cells need to fill the entire width of the collection view, we want to expose the cell's width to be settable by the view controller when the cell is set up. For that we expose a setCellWidth method that sets the width constraint of the contentView:
Swift
xxxxxxxxxx
func set(cellWidth: CGFloat) {
cellWidthConstraint.constant = cellWidth
cellWidthConstraint.isActive = true
}
Objective-C
xxxxxxxxxx
and then in the collection view's cellForItemAtIndexPath delegate method we set the width:
Swift
xxxxxxxxxx
var cellWidth = collectionView.bounds.width
if #available(iOS 11.0, *) {
cellWidth -= collectionView.adjustedContentInset.left + collectionView.adjustedContentInset.right
}
set(cellWidth: cellWidth)
Objective-C
xxxxxxxxxx
In our collection view's flow layout we must set an estimatedItemSize so the collection view will defer the size calculations to its content.
Note: It is better to set the size smaller rather than larger or constraints might break in runtime.
Swift
xxxxxxxxxx
flowLayout.estimatedItemSize = CGSize(width: kSmallArbitraryCellWidth,
height: kSmallestCellHeight)
Objective-C
xxxxxxxxxx

Typography

For our example we use a typography scheme to apply the fonts to our cell's UILabels. Please see Typography Scheme for more information.

Dynamic Type

Dynamic Type allows users to indicate a system-wide preferred text size. To support it in our cells we need to follow these steps:

Set each of the label fonts to use the dynamically sized MDC fonts in their set/update methods:

Swift

xxxxxxxxxx
func updateTitleFont() {  if (_titleFont == nil) {    _titleFont = defaultTitleFont  }  _titleLabel.font =      _titleFont.mdc_fontSized(forMaterialTextStyle: .subheadline,                               scaledForDynamicType: mdc_adjustsFontForContentSizeCategory)}

Objective-C

Add an observer in the cell to check for the UIContentSizeCategoryDidChangeNotification which tells us the a system-wide text size has been changed.

Swift

xxxxxxxxxx
NotificationCenter.default.addObserver(self,                                        selector: #selector(contentSizeCategoryDidChange(notification:)),                                        name: UIContentSizeCategory.didChangeNotification,                                        object: nil)

Objective-C

In the selector update the font sizes to reflect the change:

Swift

xxxxxxxxxx
func contentSizeCategoryDidChange(_: NSNotification) {    updateTitleFont()    updateDetailsFont()}

Objective-C

Add an observer also in the UIViewController so we can reload the collection view once there is a change:

Swift

xxxxxxxxxx
func contentSizeCategoryDidChange(_: NSNotification) {    collectionView.reloadData()}

Objective-C

iPhone X safe area support

Our collection view needs to be aware of the safe areas when being presented on iPhone X. To do so need to set its contentInsetAdjustmentBehavior to be aware of the safe area:

Swift

xxxxxxxxxx
if #available(iOS 11.0, *) {    collectionView.contentInsetAdjustmentBehavior = .always}

Objective-C

Lastly, as seen in the self-sizing section on step 2, when setting the width of the cell we need to set it to be the width of the collection view bounds minus the adjustedContentInset that now insets based on the safe area.

Landscape support

In your view controller you need to invalidate the layout of your collection view when there is an orientation change. Please see below for the desired code changes to achieve that:

Swift

xxxxxxxxxx
override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {    super.traitCollectionDidChange(previousTraitCollection)    self.collectionView.collectionViewLayout.invalidateLayout()    self.collectionView.reloadData()}​override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {    super.viewWillTransition(to: size, with: coordinator)    self.collectionView.collectionViewLayout.invalidateLayout()    coordinator.animate(alongsideTransition: nil) { (_) in    self.collectionView.collectionViewLayout.invalidateLayout()    }}

Objective-C

Right to left text support

To support right to left text we need to import MDFInternationalization:

Swift

xxxxxxxxxx
import MDFInternationalization

Objective-C

and for each of our cell's subviews me need to update the autoResizingMask:

Swift

xxxxxxxxxx
_titleLabel.autoresizingMask =  MDFTrailingMarginAutoresizingMaskForLayoutDirection(mdf_effectiveUserInterfaceLayoutDirection)

Objective-C

No iOS implementation guidance available