Image lists

Image lists display a collection of images in an organized grid.

Android Not available Web Flutter Not available iOS Not available

Usage

Image lists represent a collection of items in a repeated pattern. They help improve the visual comprehension of the content they hold.

Principles

Visual

Image lists allow users to scan content based on images.

Comparable

Image lists allow users to easily compare items within a collection.

Integrated

Image lists are responsively integrated with the surrounding content and layout.


Types

1. Standard image lists are best for items of equal importance. They have a uniform container size, ratio, and padding.

2. Quilted image lists emphasize certain items over others in a collection. They create hierarchy using varied container sizes and ratios.

3. Woven image lists facilitate the browsing of peer content. They display content in containers of varying ratios to create a rhythmic layout.

4. Masonry image lists facilitate the browsing of uncropped peer content. Container heights are sized based on the image size.

Anatomy

Image lists are comprised of containers that are set at a certain aspect ratio. Each item in an image list can display optional text and iconography below or above the image container.

1. Image container
The image container displays an image list item’s image or illustration.

2. Text labels (optional)
Text labels display one line of text related to an image list item.

3. Actionable iconography (optional)
Actionable iconography can represent related actions.

4. Text protection (optional)
Text protection is a semi-opaque scrim placed in front of imagery to keep text above it legible.

5. Image list item
Image list items represent individual items in an image list.

Padding

Padding can vary between images in an image list. The following padding values are recommended: 1, 2, 4, 8, 16, 20, 24, 32 dp.

Padding can vary between images in an image list. The following padding values are recommended: 1, 2, 4, 8, 16, 20, 24, 32 dp.


Behavior

Actions

Image lists items may be tapped, dragged, filtered, or sorted.

Image lists items may be tapped, dragged, filtered, or sorted.

Tapping an image list item displays more detail about that item.
Image list content can be filtered or sorted by date, file size, alphabetical order, or other parameters.
CautionYou can drag an image list item to reorder it, but this interaction should be disabled if images are sorted or filtered.
Don'tDon’t allow swipe gestures on individual image list items. Image lists should be perceived as a group.

Layout grid

Image list column structures don’t need to align to the layout grid. Only the perimeter of the image list itself needs to align to the...

Defined layout

Image list column structures don’t need to align to the layout grid. Only the perimeter of the image list itself needs to align to the layout grid.

An image list spanning eight columns of the layout grid, with 16dp padding

Alignment with other components

Image lists can be placed adjacent to other components in the layout grid.

An image list spanning three columns of the layout grid, with 8dp padding

Responsive

Image lists inherit the responsive behavior of the layout grid.

Image lists respond to the responsive layout grid.
Image lists are fixed to the layout grid.

Reflow

When a container increases in size, the content inside of it should also increase, or reflow, to fit the new container size appropriately. In some circumstances, the expanding container can also create space for more elements to appear.

A reflow transition can use a shared transformation to reinforce the relationship between elements. A shared transformation groups elements together and transforms them as a single unit, rather than animating each element independently. This creates a smoother visual experience and avoids the possibility of multiple transformations overlapping and competing for attention.

Grouped elements can use any of the following fading types: Fade, cross-fade, or fade through.

Diagram of an image list after reflowing to fill the space between medium and large breakpoints
Elements inside a container should reflow as the container size changes.

Scrolling

Image lists can scroll vertically or horizontally. All items in an image list must scroll together as a collection. Image cropping can be used to...

Image lists can scroll vertically or horizontally. All items in an image list must scroll together as a collection. Image cropping can be used to indicate scroll direction.

Image list items scroll together.
Image lists can scroll horizontally.

Scaling and adaptation

As screen sizes increase, there are more opportunities for variation in text and image composition.

As screen sizes increase, there are more opportunities for variation in text and image composition. Large screens can create more space for images and text by swapping lists for image lists.

Example UI with a large image list
Example of list of items after expanding into a large image list. Large screen layouts can accommodate more immersive imagery and expressive typography.

Types

Standard image list

Standard image lists are best for items of equal importance. They have a uniform container size, ratio, and padding.

Standard image lists are best for items of equal importance. They have a uniform container size, ratio, and padding.

Standard image lists can be displayed with or without text labels.
1. image list with images only
2. image list with images and text labels
In compact layouts, labels can appear above the image container using an image treatment that provides text protection to ensure legibility.

Quilted image list

Quilted image lists emphasize certain items over others in a collection. They use varied container sizes and ratios to create hierarchy across images.

Quilted image lists emphasize certain items over others in a collection. They use varied container sizes and ratios to create hierarchy across images.

Don'tQuilted image lists shouldn’t display text below the image container, as it disrupts the layout.

Woven image list

Woven image lists use alternating container ratios to create a rhythmic layout. A woven image list is best for browsing peer content.

Woven image lists use alternating container ratios to create a rhythmic layout. A woven image list is best for browsing peer content.


Masonry image list

Masonry image lists use dynamically sized container heights that reflect the aspect ratio of each image. This image list is best used for browsing uncropped...

Masonry image lists use dynamically sized container heights that reflect the aspect ratio of each image. This image list is best used for browsing uncropped peer content.


Theming

Crane Material Theme

This travel app’s image lists have been customized using Material Theming. Areas of customization include color, typography, and shape. Crane is a travel app that...

Color

Crane’s image list text uses custom color.

Element Category Attribute Value
Surface Surface Color
Opacity
#FFFFFF
100%
Text On Surface Color
Opacity
#000000
87%

Typography

Crane’s image list text uses custom typography.

Element Category Attribute Value
Text Subtitle 1 Typeface
Font
Size
Case
Raleway
Medium
16
Title case

Shape

Crane’s image lists have custom corner shapes on image containers.

Element Category Attribute Value
Container Medium component Family
Size
Round
16;16;16;16dp

Owl Material Theme

This education app’s image list text has been customized using Material Theming. Owl is an educational app that provides courses for people who want to...

Typography

Owl’s image list text uses custom typography.

Element Category Attribute Value
Text Subtitle 1 Typeface
Font
Size
Case
Rubik
Medium
16
Title case

Shape

Owl’s image lists have custom corner shapes on image containers.

Element Category Attribute Value
Container Medium component Family
Size
Round
0;0;0;0dp

Shrine Material Theme

This retail app’s image lists have been customized using Material Theming. Areas of customization include color and typography. Shrine is a lifestyle and fashion brand...

Color

Shrine’s image list text uses custom color.

Element Category Attribute Value
Surface Surface Color
Opacity
#FFFBFA
100%
Text On Surface Color
Opacity
#442C2E
100%

Typography

Shrine’s image list text uses custom typography.

Element Category Attribute Value
Text Subtitle 1 Typeface
Font
Size
Case
Raleway
Medium
16
Title case

Shape

Shrine's image lists have custom corner shapes on image containers.

Element Category Attribute Value
Container Medium component Family
Size
Cut
16;16;16;16dp

Specs

Standard

  • Measurement 4
  • Measurement 4
  • Measurement 4
  • 1x1
 

Quilted

  • Measurement 4
  • Measurement 4
  • 1x1
  • 2x1
  • 1x1
 

Masonry—mobile

  • Measurement 4
  • Measurement 4
  • Measurement 4
  • Measurement 4
  • Measurement 4
  • 174224
 

Masonry—desktop

  • Measurement 4
  • Measurement 4
 
  • Measurement 28
  • Measurement 32
  • Measurement 8
  • 2424
 

Masonry—tablet

  • Measurement 4
  • Measurement 4
  • Measurement 4
  • Measurement 4
  • Measurement C
  • Measurement 24
  • Measurement 48
  • Measurement 12
  • Measurement 12
  • Measurement 12
  • Measurement 48
  • 192246
 

Woven

  • Measurement 24
  • Measurement 24
  • Measurement 24
  • Measurement 28
  • 1x1
  • 5x7
 
No Android implementation guidance available

Installation

Basic Usage

HTML Structure

The HTML structure for a Standard Image List is as follows:

Styles

The HTML structure above would be combined with an invocation of the standard-columns mixin, to establish how many columns should be displayed per line:

Images in a Standard Image list are constrained to 1:1 aspect ratio by default; this can be overridden using the aspect mixin documented below.

Variants

Masonry Image List

The Masonry Image List variant presents images vertically arranged into several columns, using CSS Columns. In this layout, images may be any combination of aspect ratios.

Note: Masonry Image List items do not include the mdc-image-list__image-aspect-container element, since images in the list are not expected to be locked to a common aspect ratio.

This would be combined with an invocation of the mdc-image-list-masonry-columns mixin, to establish how many columns should be displayed:

Style Customization

CSS Classes

CSS ClassDescription
mdc-image-listMandatory. Indicates the root Image List element.
mdc-image-list--masonryOptional. Indicates that this Image List should use the Masonry variant.
mdc-image-list--with-text-protectionOptional. Indicates that supporting content should be positioned in a scrim overlaying each image (instead of positioned separately under each image).
mdc-image-list__itemMandatory. Indicates each item in an Image List.
mdc-image-list__image-aspect-containerOptional. Parent of each item's image element, responsible for constraining aspect ratio. This element may be omitted entirely if images are already sized to the correct aspect ratio.
mdc-image-list__imageMandatory. Indicates the image element in each item.
mdc-image-list__supportingOptional. Indicates the area within each item containing the supporting text label, if the Image List contains text labels.
mdc-image-list__labelOptional. Indicates the text label in each item, if the Image List contains text labels.

Sass Mixins

MixinDescription
aspect($width-height-ratio)Styles the aspect container elements within an Image List to conform to the given ratio, where 1 is 1:1, greater than 1 is wider, and less than 1 is taller.
shape-radius($radius, $rtl-reflexive)Sets the rounded shape to image list item with given radius size. Set $rtl-reflexive to true to flip radius values in RTL context, defaults to false.
standard-columns($column-count, $gutter-size)Styles a Standard Image List to display the given number of columns. $gutter-size is optional and overrides the default amount of space between items.
masonry-columns($column-count, $gutter-size)Styles a Masonry Image List to display the given number of columns. $gutter-size is optional and overrides the default amount of space between items.

Note: Only one of the *-columns mixins should be used for any given Image List. Use the mixin appropriate to the variant being used.

Additional Information

Constraining width

The *-columns mixins will grow and shrink items based on the Image List's overall width. Depending on placement, this could be directly related to the viewport width, and images could become exceedingly large compared to their actual rendered size. This can be restricted by using any of min-width, width, or max-width on the Image List:

Note: Remember that any specified width will apply to the entire list, so be sure to account for the gutters as well.

Changing number of columns across breakpoints

Presenting a different number of columns for different viewport sizes is straightforward, since the only thing that needs to be changed are styles:

Using div in place of img to enforce aspect ratio

Note: This advice is not applicable to Masonry Image List, where images do not share a common aspect ratio.

Images in an Image List typically use the img element. However, if your assets don't have the same aspect ratio as specified for list items, they will become distorted. In these cases, you can use a div element in place of img, and set the background-image of each.

Note: Ensuring your images are appropriately-sized prior to serving them to browsers is the most efficient and ideal approach to using MDC Image List. The div alternative is provided as a convenience. If you use this alternative, make sure to also include the mdc-image-list__image-aspect-container element around each item's image.

No Web implementation guidance available
No Flutter implementation guidance available
No iOS implementation guidance available

Up next