1 |
|
2 | title: "Grid Lists"
|
3 | layout: detail
|
4 | section: components
|
5 | excerpt: "An RTL-aware Material Design grid list component."
|
6 | iconId: card
|
7 | path: /catalog/grid-lists/
|
8 | -->
|
9 |
|
10 | ## Important - Deprecation Notice
|
11 |
|
12 | The existing `MDCGridList` component and styles will be removed in a future release. Some of its functionality
|
13 | will be available in the [MDC Image List](../mdc-image-list) package instead. Bugs and feature requests
|
14 | will no longer be accepted for the `mdc-grid-list` package. It is recommended that you migrate to the
|
15 | `mdc-image-list` package to continue to receive new features and updates.
|
16 |
|
17 | # Grid Lists
|
18 |
|
19 | MDC Grid List provides a RTL-aware Material Design Grid list component adhering to the Material Design Grid list spec.
|
20 | Grid Lists are best suited for presenting homogeneous data, typically images.
|
21 | Each item in a grid list is called a **tile**. Tiles maintain consistent width, height, and padding
|
22 | across screen sizes.
|
23 |
|
24 | ## Installation
|
25 |
|
26 | ```
|
27 | npm install @material/grid-list
|
28 | ```
|
29 |
|
30 |
|
31 | ## Usage
|
32 |
|
33 | Basic Grid list has the following structure:
|
34 |
|
35 | ```html
|
36 | <div class="mdc-grid-list">
|
37 | <ul class="mdc-grid-list__tiles">
|
38 | <li class="mdc-grid-tile">
|
39 | <div class="mdc-grid-tile__primary">
|
40 | <img class="mdc-grid-tile__primary-content" src="my-image.jpg" />
|
41 | </div>
|
42 | <span class="mdc-grid-tile__secondary">
|
43 | <span class="mdc-grid-tile__title">Title</span>
|
44 | </span>
|
45 | </li>
|
46 | <li class="mdc-grid-tile">
|
47 | <div class="mdc-grid-tile__primary">
|
48 | <img class="mdc-grid-tile__primary-content" src="my-image.jpg" />
|
49 | </div>
|
50 | <span class="mdc-grid-tile__secondary">
|
51 | <span class="mdc-grid-tile__title">Title</span>
|
52 | </span>
|
53 | </li>
|
54 | </ul>
|
55 | </div>
|
56 | ```
|
57 |
|
58 | The above markup will give you a Grid list of tiles that:
|
59 |
|
60 | - Have 4px padding in between themselves
|
61 | - Have a 1x1 aspect ratio
|
62 | - Have a one-line footer caption with no icon
|
63 |
|
64 | You just need to put the content you want to load in `src` of
|
65 | `<img class="mdc-grid-tile__primary-content" src="..."/>`. However, if your
|
66 | assets don't have the same aspect ratio you as specified in the tile, it will
|
67 | distort those assets. We provide a solution of that case in
|
68 | [Using a div in place of an img](#using-a-div-in-place-of-an-img) section.
|
69 |
|
70 |
|
71 | ### Setting the tile width
|
72 |
|
73 | The tile width is set to 200px by default. There are three ways that you can
|
74 | overwrite the default value for your grid list:
|
75 |
|
76 | 1. Using CSS variables
|
77 |
|
78 | ```css
|
79 | .mdc-grid-tile {
|
80 | --mdc-grid-list-tile-width: 300px;
|
81 | }
|
82 | ```
|
83 |
|
84 | 2. Overwriting SCSS variable
|
85 |
|
86 | You can overwrite the scss variable by
|
87 |
|
88 | ```scss
|
89 | $mdc-grid-list-tile-width: 300px;
|
90 | @import "@material/grid-list/mdc-grid-list";
|
91 | ```
|
92 |
|
93 | 3. Add own style to tile
|
94 |
|
95 | ```html
|
96 | <style>
|
97 | .my-grid-list .mdc-grid-tile {
|
98 | width : 300px;
|
99 | }
|
100 | </style>
|
101 | <div class="mdc-grid-list my-grid-list">
|
102 | <ul class="mdc-grid-list__tiles">
|
103 | <li class="mdc-grid-tile"></li>
|
104 | ...
|
105 | </ul>
|
106 | </div>
|
107 | ```
|
108 |
|
109 | ### Change tile padding
|
110 |
|
111 | Grid list tiles can have 1px padding instead of 4px by adding
|
112 | `mdc-grid-list--tile-gutter-1` modifier.
|
113 |
|
114 | ```html
|
115 | <div class="mdc-grid-list mdc-grid-list--tile-gutter-1">
|
116 | <ul class="mdc-grid-list__tiles">
|
117 | ...
|
118 | </ul>
|
119 | </div>
|
120 | ```
|
121 |
|
122 | ### Image only tile
|
123 |
|
124 | Grid lists support image only tile. You can remove `mdc-grid-tile__secondary`
|
125 | and create a image only grid list.
|
126 |
|
127 | ```html
|
128 | <div class="mdc-grid-list mdc-grid-list--tile-gutter-1">
|
129 | <ul class="mdc-grid-list__tiles">
|
130 | <li class="mdc-grid-tile">
|
131 | <div class="mdc-grid-tile__primary">
|
132 | <img class="mdc-grid-tile__primary-content" src="images/1-1.jpg" />
|
133 | </div>
|
134 | </li>
|
135 | </ul>
|
136 | </div>
|
137 | ```
|
138 |
|
139 | ### Header caption
|
140 |
|
141 | Grid lists support header caption. You can change the footer caption to be a
|
142 | header caption by adding `mdc-grid-list--header-caption` modifier.
|
143 |
|
144 | ```html
|
145 | <div class="mdc-grid-list mdc-grid-list--header-caption">
|
146 | <ul class="mdc-grid-list__tiles">
|
147 | ...
|
148 | </ul>
|
149 | </div>
|
150 | ```
|
151 |
|
152 | ### Add support text to secondary content (caption)
|
153 |
|
154 | Grid lists support a one-line caption by default. You can add an additional line of support
|
155 | text if needed by adding the `mdc-grid-list--twoline-caption` modifier and additional
|
156 | markup
|
157 |
|
158 | ```html
|
159 | <div class="mdc-grid-list mdc-grid-list--twoline-caption">
|
160 | <ul class="mdc-grid-list__tiles">
|
161 | <li class="mdc-grid-tile">
|
162 | <div class="mdc-grid-tile__primary">
|
163 | <img class="mdc-grid-tile__primary-content" src="my-image.jpg" />
|
164 | </div>
|
165 | <span class="mdc-grid-tile__secondary">
|
166 | <span class="mdc-grid-tile__title">Title</span>
|
167 | <span class="mdc-grid-tile__support-text">Support text</span>
|
168 | </span>
|
169 | </li>
|
170 | </ul>
|
171 | </div>
|
172 | ```
|
173 |
|
174 | ### Add icon to secondary content (caption)
|
175 |
|
176 | You can add an icon to a caption by adding `mdc-grid-list--with-icon-align-start` or
|
177 | `mdc-grid-list--with-icon-align-end` and changing the markup.
|
178 |
|
179 | ```html
|
180 | <div class="mdc-grid-list mdc-grid-list--with-icon-align-start">
|
181 | <ul class="mdc-grid-list__tiles">
|
182 | <li class="mdc-grid-tile">
|
183 | <div class="mdc-grid-tile__primary">
|
184 | <img class="mdc-grid-tile__primary-content" src="my-image.jpg" />
|
185 | </div>
|
186 | <span class="mdc-grid-tile__secondary">
|
187 | <i class="mdc-grid-tile__icon material-icons">star_border</i>
|
188 | <span class="mdc-grid-tile__title">Title</span>
|
189 | </span>
|
190 | </li>
|
191 | </ul>
|
192 | </div>
|
193 | ```
|
194 |
|
195 | ### Change aspect ratio of tile
|
196 |
|
197 | Grid list tiles support all material guideline recommended aspect ratio:
|
198 |
|
199 | - 1x1
|
200 | - 16x9
|
201 | - 2x3
|
202 | - 3x2
|
203 | - 4x3
|
204 | - 3x4
|
205 |
|
206 | You can use the modifier class `mdc-grid-list--tile-aspect-$ASPECT_RATIO` to apply these aspect
|
207 | ratios to your grid list. Simply replace `$ASPECT_RATIO` with any of the predefined ratios.
|
208 |
|
209 | ```html
|
210 | <!-- Example of 16x9 tile -->
|
211 | <div class="mdc-grid-list mdc-grid-list--tile-aspect-16x9">
|
212 | <ul class="mdc-grid-list__tiles">
|
213 | ...
|
214 | </ul>
|
215 | </div>
|
216 | ```
|
217 |
|
218 | As pointed out in the previous section, if your
|
219 | assets don't have the same aspect ratio you as specified in the tile, it will
|
220 | distort those assets. We provide a solution of that case in
|
221 | [Using a div in place of an img](#using-a-div-in-place-of-an-img) section.
|
222 |
|
223 | ### Using a div in place of an img
|
224 |
|
225 | In case you cannot ensure all your assets will have the same aspect ratio, you
|
226 | can use `div` instead of `img` markup. It will resize the assets to cover the tile
|
227 | and crop the assets to display the center part.
|
228 |
|
229 | ```html
|
230 | <style>
|
231 | .my-tile-image {
|
232 | background-image: url(my-image.jpg);
|
233 | }
|
234 | </style>
|
235 |
|
236 | <div class="mdc-grid-list">
|
237 | <ul class="mdc-grid-list__tiles">
|
238 | <li class="mdc-grid-tile">
|
239 | <div class="mdc-grid-tile__primary">
|
240 | <div class="mdc-grid-tile__primary-content my-tile-image"></div>
|
241 | </div>
|
242 | <span class="mdc-grid-tile__secondary">
|
243 | <span class="mdc-grid-tile__title">Title</span>
|
244 | </span>
|
245 | </li>
|
246 | </ul>
|
247 | </div>
|
248 | ```
|
249 |
|
250 | However, the method results in a less semantic markup, so we don't use this method by
|
251 | default.
|
252 |
|
253 | ### RTL Support
|
254 |
|
255 | `mdc-grid-list` is automatically RTL-aware, and will re-position elements whenever
|
256 | it, or its ancestors, have a `dir="rtl"` attribute.
|
257 |
|
258 | ### Theme
|
259 |
|
260 | `mdc-grid-list` supports theming. `mdc-grid-tile__primary` uses the theme's background
|
261 | color for its background color. `mdc-grid-tile__secondary` uses the theme's primary
|
262 | color for its background color, and the theme's `on-primary` color for its text color.
|
263 |
|
264 | ### `MDCGridListFoundation`
|
265 |
|
266 | Method Signature | Description
|
267 | --- | ---
|
268 | `alignCenter() => void` | Centers tiles horizontally within their parent container.
|
269 |
|
270 | ### `MDCGridListAdapter`
|
271 |
|
272 | Method Signature | Description
|
273 | --- | ---
|
274 | `getOffsetWidth() => number` | Get root element `mdc-grid-list` offsetWidth.
|
275 | `getNumberOfTiles() => number` | Get the number of mdc-grid-tile elements contained within the grid list.
|
276 | `getOffsetWidthForTileAtIndex(index: number) => number` | Get offsetWidth of `mdc-grid-tile` at specified index.
|
277 | `setStyleForTilesElement(property: string, value: number) => void` | Set `mdc-grid-list__tiles` style property to provided value.
|
278 | `registerResizeHandler(handler: EventListener) => void` | Registers a handler to be called when the surface (or its viewport) resizes. Our default implementation adds the handler as a listener to the window's `resize()` event.
|
279 | `deregisterResizeHandler(handler: EventListener) => void` | Unregisters a handler to be called when the surface (or its viewport) resizes. Our default implementation removes the handler as a listener to the window's `resize()` event.
|