Lists

Lists are continuous, vertical indexes of text or images.

Android check Web Flutter iOS

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.

1. List
2. Row
3. List item 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).

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.

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

A text list.
A single-line list with icons and text.
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.

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

A two-line list, with an icon and meta icon.
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 with an avatar.
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.

1. Secondary action
This checkbox is the list item’s secondary action.

2. Primary action
This checkbox is both the list item’s primary action and state indicator.

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.
An expanded list.

Switch

Tapping the list control expands the list.

Reorder

Usually appearing in edit mode, dragging lists items moves them to other locations within the list. This reorder icon is the list item's secondary action.

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...

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...

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

Styles

JavaScript

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

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:

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.

KeyAction
ArrowUpWhen the list is in a vertical orientation (default), it will cause the previous list item to receive focus.
ArrowDownWhen the list is in a vertical orientation (default), it will cause the next list item to receive focus.
ArrowLeftWhen the list is in a horizontal orientation, it will cause the previous list item to receive focus.
ArrowRightWhen the list is in a horizontal orientation, it will cause the next list item to receive focus.
HomeWill cause the first list item in the list to receive focus.
EndWill cause the last list item in the list to receive focus.
SpaceWill cause the currently focused list item to become selected/deselected if singleSelection=true.
EnterWill 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

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.

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.

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.

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.

OR

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.

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.

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".

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.

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 ClassDescription
mdc-listMandatory, for the list element.
mdc-list--denseOptional, styles the density of the list, making it appear more compact.
mdc-list--textual-listOptional, configures lists that start with text
(e.g., do not have a leading tile).
mdc-list--avatar-listOptional, configures the leading tile of each row to
display avatars.
mdc-list--icon-listOptional, configures the leading tile of each row to
display icons.
mdc-list--image-listOptional, configures the leading tile of each row to
display images.
mdc-list--thumbnail-listOptional, 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-listOptional, configures the leading tile of each row to
display videos.
mdc-list--two-lineOptional, modifier to style list with two lines (primary and secondary lines).
mdc-list-itemMandatory, for the list item element.
mdc-list-item__textMandatory. Wrapper for list item text content (displayed as middle column of the list item).
mdc-list-item__primary-textOptional, primary text for the list item. Should be the child of mdc-list-item__text.
mdc-list-item__secondary-textOptional, secondary text for the list item. Displayed below the primary text. Should be the child of mdc-list-item__text.
mdc-list-item--disabledOptional, styles the row in the disabled state.
mdc-list-item--selectedOptional, styles the row in the selected* state.
mdc-list-item--activatedOptional, styles the row in the activated* state.
mdc-list-item__graphicOptional, 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__metaOptional, the last tile in the row (in LTR languages,
the last column of the list item). Typically small text, icon, or image.
mdc-list-groupOptional, wrapper around two or more mdc-list elements to be grouped together.
mdc-list-group__subheaderOptional, heading text displayed above each list in a group.
mdc-list-dividerOptional, for list divider element.
mdc-list-divider--paddedOptional, 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--insetOptional, 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-leadingOptional, increases the leading margin of
the divider so that it does not intersect the graphics column.
mdc-list-divider--inset-trailingOptional, increases the trailing margin of
the divider so that it coincides with the item's padding.
mdc-list-divider--inset-paddingOptional, 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

MixinDescription
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

PropertyValue TypeDescription
verticalboolean (write-only)Proxies to the foundation's setVerticalOrientation() method.
listElementsArray<Element> (read-only)Returns all list item elements including disabled list items.
wrapFocusboolean (write-only)Proxies to the foundation's setWrapFocus() method.
typeaheadInProgressboolean (read-only)Proxies to foundation's isTypeaheadInProgress method.
hasTypeaheadboolean (write-only)Proxies to the foundation's setHasTypeahead() method.
singleSelectionboolean (write-only)Proxies to the foundation's setSingleSelection() method.
selectedIndexMDCListIndexProxies to the foundation's getSelectedIndex() and setSelectedIndex() methods.
Method SignatureDescription
layout() => voidRecalculates layout and orientation.
getPrimaryText(item: Element) => stringFetches the primary text in the given element.
initializeListType() => voidInitialize selectedIndex value based on pre-selected checkbox list items, single selection or radio.
setEnabled(itemIndex: number, isEnabled: boolean) => voidUpdates the list item at itemIndex to the desired isEnabled state.

Events

Event Nameevent.detailDescription
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".

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.

MDCListAdapter

Method SignatureDescription
getListItemCount() => NumberReturns the total number of list items (elements with mdc-list-item class) that are direct children of the root_ element.
getFocusedElementIndex() => NumberReturns the index value of the currently focused element.
`getAttributeForElementIndex(index: number, attribute: string) => stringnull`
setAttributeForElementIndex(index: Number, attr: String, value: String) => voidSets the attr attribute to value for the list item at index.
addClassForElementIndex(index: Number, className: String) => voidAdds the className class to the list item at index.
removeClassForElementIndex(index: Number, className: String) => voidRemoves the className class to the list item at index.
focusItemAtIndex(index: Number) => voidFocuses the list item at the index value specified.
setTabIndexForListItemChildren(index: Number, value: Number) => voidSets the tabindex attribute to value for each child button or anchor element in the list item at the index specified.
hasRadioAtIndex(index: number) => booleanReturns true if radio button is present at given list item index.
hasCheckboxAtIndex(index: number) => booleanReturns true if checkbox is present at given list item index.
isCheckboxCheckedAtIndex(index: number) => booleanReturns true if checkbox inside a list item is checked.
setCheckedCheckboxOrRadioAtIndex(index: number, isChecked: boolean) => voidSets the checked status of checkbox or radio at given list item index.
notifyAction(index: number) => voidNotifies user action on list item including keyboard and mouse actions.
isFocusInsideList() => booleanReturns true if the current focused element is inside list root.
isRootFocused() => booleanReturns true if root element is focused.
listItemAtIndexHasClass(index: number, className: string) => booleanReturns 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 SignatureDescription
setWrapFocus(value: Boolean) => voidSets 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) => voidSets 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) => voidSets the list to be a selection list. Enables the enter and space keys for selecting/deselecting a list item.
getSelectedIndex() => MDCListIndexGets 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) => voidSets 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) => voidSets the selection logic to apply/remove the mdc-list-item--activated class.
handleFocusIn(evt: Event) => voidHandles the changing of tabindex to 0 for all button and anchor elements when a list item receives focus.
handleFocusOut(evt: Event) => voidHandles the changing of tabindex to -1 for all button and anchor elements when a list item loses focus.
handleKeydown(evt: Event) => voidHandles determining if a focus action should occur when a key event is triggered.
handleClick(evt: Event) => voidHandles toggling the selected/deselected state for a list item when clicked. This method is only used by the single selection list.
focusNextElement(index: number) => numberHandles focusing the next element using the current index. Returns focused element index.
focusPrevElement(index: number) => numberHandles focusing the previous element using the current index. Returns focused element index.
focusFirstElement() => numberHandles focusing the first element in a list. Returns focused element index.
focusLastElement() => numberHandles focusing the last element in a list. Returns focused element index.
setEnabled(itemIndex: number, isEnabled: Boolean) => voidUpdates the list item's disabled state.
setHasTypeahead(hasTypeahead: Boolean) => voidSets whether typeahead is enabled on the list.
isTypeaheadInProgress() => BooleanReturns whether typeahead is currently matching a user-specified prefix.
typeaheadMatchItem(nextChar: string) => numberAdds a character to the typeahead buffer and returns index of the next item in the list matching the buffer.
clearTypeaheadBuffer() => voidClears 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:

List anatomy diagram showing list, row, and list item content

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:

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

Types

There are three list types:

  1. Single-line list
  2. Two-line list
  3. Three-line list

Composite image of the 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

Single-line list example

Single-line list key properties

  1. List
  2. Row
  3. List item
  4. Supporting visuals
  5. Primary text
  6. Metadata

List properties for single line list

 Property
Padding around the listpadding on ListView

Row properties for single line list

 Property
Enabled rowenabled on ListTile
Selected rowselected on ListTile
Padding on rowspadding 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
Iconleading on ListTile

Primary text for single line list

 Property
Text labeltitle on ListTile
Text colorWithin 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.
TypographyWithin 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 labeltrailing on ListTile
Text colorWithin 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.
TypographyWithin 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 actionAdd interactive widget to leading on ListTile
Secondary actionAdd 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

Two-line list example

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:

  1. Supporting visuals
  2. Primary text
  3. Secondary text
  4. Metadata
  5. Controls

Supporting visuals for two line list

 Property
Iconleading on ListTile

Primary text for two line list

 Property
Text labeltitle on ListTile
Text colorWithin 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.
TypographyWithin 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 labelsubtitle on ListTile
Text colorWithin 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.
TypographyWithin 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 labeltrailing on ListTile
Text colorWithin 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.
TypographyWithin 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 actionAdd interactive widget to leading on ListTile
Secondary actionAdd 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

Three-line list example

Three-line list key properties

The following are tables of the list item contents:

  1. Supporting visuals
  2. Primary text
  3. Secondary text
  4. Tertiary text
  5. Metadata
  6. Controls

Supporting visuals for three line list

 Property
Iconleading on ListTile

Primary text for three line list

 Property
Text labeltitle on ListTile
Text colorWithin 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.
TypographyWithin 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 labelsubtitle on ListTile
Text colorWithin 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.
TypographyWithin 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 labelsubtitle on ListTile with isThreeLine set to true
Text colorWithin 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.
TypographyWithin 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 labeltrailing on ListTile
Text labelNot by default but can be made by using ListTile() and use property trailing
Text colorWithin 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.
TypographyWithin 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 actionAdd interactive widget to leading on ListTile
Secondary actionAdd interactive widget to trailing on ListTile

Theming lists

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

Three-line list example with theming

No Flutter implementation guidance available

Using lists

Installing

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

Then, run the following command:

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

Swift

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.

Animation showing a list of MDCBaseCell views with Ripple effects

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

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

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:

List anatomy diagram showing list, row, and list item content

This list item consists of the following attributes:

  1. Leading image view
  2. Title label and detail label
  3. 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

 AttributeRelated methodsDefault value
ColorrippleColor-setRippleColor:
-setRippleColor
On surface color at 0.12 opacity
Elevationelevation-setElevation:
-elevation
0

Icon attributes

 AttributeRelated methodsDefault value
Leading imageleadingImageViewN/AN/A
Trailing imagetrailingImageViewN/AN/A

Text label attributes

 AttributeRelated methodsDefault value
Title texttitleLabelN/AN/A
Detail texttitleLabelN/AN/A

Types

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

Composite image of the three list types

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

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

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

Objective-C

Theming

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

A two-line list item with example text and 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:

Then run the installer:

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

Swift

Objective-C

Building your own list item

The example files can be found here

List Cell Example

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:

  1. Add an MDCInkView property to your custom cell.

  2. Initialize MDCInkView on init and add it as a subview:

    Swift

    Objective-C

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

  4. 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

    Objective-C

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

    Swift

    Objective-C

  6. 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

    Objective-C

    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:

  1. 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

    Objective-C

    This is in order to support the changing layout if an image is set or not.

  2. 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

    Objective-C

    and then in the collection view's cellForItemAtIndexPath delegate method we set the width:

    Swift

    Objective-C

  3. 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

    Objective-C

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:

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

    Swift

    Objective-C

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

Swift

Objective-C

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

Swift

Objective-C

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

Swift

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

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

Objective-C

Right to left text support

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

Swift

Objective-C

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

Swift

Objective-C

No iOS implementation guidance available

Up next