1 |
|
2 | title: "Image List"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "An RTL-aware Material Design image list component."
|
6 | iconId: card
|
7 | path: /catalog/image-lists/
|
8 | -->
|
9 |
|
10 | # Image List
|
11 |
|
12 | MDC Image List provides a RTL-aware Material Design image list component. An Image List consists of several items,
|
13 | each 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 | ```
|
29 | npm install @material/image-list
|
30 | ```
|
31 |
|
32 | ## Basic Usage
|
33 |
|
34 | ### HTML Structure
|
35 |
|
36 | The 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 |
|
58 | The HTML structure above would be combined with an invocation of the `standard-columns` mixin,
|
59 | to 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 |
|
69 | Images 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 |
|
76 | The 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
|
78 | combination 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
|
93 | images in the list are not expected to be locked to a common aspect ratio.
|
94 |
|
95 | This would be combined with an invocation of the `mdc-image-list-masonry-columns` mixin, to establish how many columns
|
96 | should 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 |
|
108 | CSS 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 |
|
121 | Mixin | 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 |
|
135 | The `*-columns` mixins will grow and shrink items based on the Image List's overall width. Depending on
|
136 | placement, this could be directly related to the viewport width, and images could become exceedingly large compared to
|
137 | their actual rendered size. This can be restricted by using any of `min-width`, `width`, or `max-width` on the Image
|
138 | List:
|
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
|
151 | as well.
|
152 |
|
153 | #### Changing number of columns across breakpoints
|
154 |
|
155 | Presenting a different number of columns for different viewport sizes is straightforward, since the only thing that
|
156 | needs 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 |
|
174 | Images in an Image List typically use the `img` element. However, if your assets don't have the same aspect ratio as
|
175 | specified for list items, they will become distorted. In these cases, you can use a `div` element in place of `img`,
|
176 | and 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
|
179 | ideal approach to using MDC Image List. The `div` alternative is provided as a convenience. If you use this alternative,
|
180 | make sure to also include the `mdc-image-list__image-aspect-container` element around each item's image.
|