UNPKG

6.64 kBMarkdownView Raw
1<!--docs:
2title: "Image List"
3layout: detail
4section: components
5excerpt: "An RTL-aware Material Design image list component."
6iconId: card
7path: /catalog/image-lists/
8-->
9
10# Image List
11
12MDC Image List provides a RTL-aware Material Design image list component. An Image List consists of several items,
13each containing an image and optionally supporting content (i.e. a text label).
14
15## Design & API Documentation
16
17<ul class="icon-list">
18 <li class="icon-list-item icon-list-item--spec">
19 <a href="https://material.io/go/design-image-list">Material Design guidelines: Image list</a>
20 </li>
21 <li class="icon-list-item icon-list-item--link">
22 <a href="https://material-components.github.io/material-components-web-catalog/#/component/image-list">Demo</a>
23 </li>
24</ul>
25
26## Installation
27
28```
29npm install @material/image-list
30```
31
32## Basic Usage
33
34### HTML Structure
35
36The HTML structure for a Standard Image List is as follows:
37
38```html
39<ul class="mdc-image-list my-image-list">
40 <li class="mdc-image-list__item">
41 <div class="mdc-image-list__image-aspect-container">
42 <img class="mdc-image-list__image" src="...">
43 </div>
44 <div class="mdc-image-list__supporting">
45 <span class="mdc-image-list__label">Text label</span>
46 </div>
47 </li>
48 ...
49</ul>
50```
51
52### Styles
53
54```scss
55@use "@material/image-list/mdc-image-list";
56```
57
58The HTML structure above would be combined with an invocation of the `standard-columns` mixin,
59to establish how many columns should be displayed per line:
60
61```scss
62@use "@material/image-list";
63
64.my-image-list {
65 @include image-list.standard-columns(5);
66}
67```
68
69Images in a Standard Image list are constrained to 1:1 aspect ratio by default; this can be overridden using the
70`aspect` mixin documented below.
71
72## Variants
73
74### Masonry Image List
75
76The Masonry Image List variant presents images vertically arranged into several columns, using
77[CSS Columns](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns). In this layout, images may be any
78combination of aspect ratios.
79
80```html
81<ul class="mdc-image-list mdc-image-list--masonry my-masonry-image-list">
82 <li class="mdc-image-list__item">
83 <img class="mdc-image-list__image" src="...">
84 <div class="mdc-image-list__supporting">
85 <span class="mdc-image-list__label">Text label</span>
86 </div>
87 </li>
88 ...
89</ul>
90```
91
92> **Note:** Masonry Image List items _do not_ include the `mdc-image-list__image-aspect-container` element, since
93images in the list are not expected to be locked to a common aspect ratio.
94
95This would be combined with an invocation of the `mdc-image-list-masonry-columns` mixin, to establish how many columns
96should be displayed:
97
98```scss
99.my-masonry-image-list {
100 @include image-list.masonry-columns(5);
101}
102```
103
104## Style Customization
105
106### CSS Classes
107
108CSS Class | Description
109--- | ---
110`mdc-image-list` | Mandatory. Indicates the root Image List element.
111`mdc-image-list--masonry` | Optional. Indicates that this Image List should use the Masonry variant.
112`mdc-image-list--with-text-protection` | Optional. Indicates that supporting content should be positioned in a scrim overlaying each image (instead of positioned separately under each image).
113`mdc-image-list__item` | Mandatory. Indicates each item in an Image List.
114`mdc-image-list__image-aspect-container` | Optional. 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.
115`mdc-image-list__image` | Mandatory. Indicates the image element in each item.
116`mdc-image-list__supporting` | Optional. Indicates the area within each item containing the supporting text label, if the Image List contains text labels.
117`mdc-image-list__label` | Optional. Indicates the text label in each item, if the Image List contains text labels.
118
119### Sass Mixins
120
121Mixin | Description
122--- | ---
123`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.
124`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.
125`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.
126`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.
127
128> **Note:** Only one of the `*-columns` mixins should be used for any given Image List.
129> Use the mixin appropriate to the variant being used.
130
131### Additional Information
132
133#### Constraining width
134
135The `*-columns` mixins will grow and shrink items based on the Image List's overall width. Depending on
136placement, this could be directly related to the viewport width, and images could become exceedingly large compared to
137their actual rendered size. This can be restricted by using any of `min-width`, `width`, or `max-width` on the Image
138List:
139
140```scss
141@use "@material/image-list";
142
143.my-image-list {
144 @include image-list.standard-columns(5);
145
146 max-width: 960px;
147}
148```
149
150> **Note:** Remember that any specified width will apply to the _entire_ list, so be sure to account for the gutters
151as well.
152
153#### Changing number of columns across breakpoints
154
155Presenting a different number of columns for different viewport sizes is straightforward, since the only thing that
156needs to be changed are styles:
157
158```scss
159.my-image-list {
160 @include image-list.standard-columns(5);
161}
162
163@media (max-width: 599px) {
164 .my-image-list {
165 @include image-list.standard-columns(3);
166 }
167}
168```
169
170#### Using div in place of img to enforce aspect ratio
171
172> **Note:** This advice is not applicable to Masonry Image List, where images do not share a common aspect ratio.
173
174Images in an Image List typically use the `img` element. However, if your assets don't have the same aspect ratio as
175specified for list items, they will become distorted. In these cases, you can use a `div` element in place of `img`,
176and set the `background-image` of each.
177
178> **Note:** Ensuring your images are appropriately-sized prior to serving them to browsers is the most efficient and
179ideal approach to using MDC Image List. The `div` alternative is provided as a convenience. If you use this alternative,
180make sure to also include the `mdc-image-list__image-aspect-container` element around each item's image.