1
1
# Migrating to MDC-based Angular Material Components
2
2
3
- In Angular Material v15, many of the components have been refactored to be based on the official
3
+ In Angular Material v15, many of the components have been refactored to be based on the official
4
4
[ Material Design Components for Web (MDC)] ( https://github.com/material-components/material-components-web ) .
5
5
The components from the following imports have been refactored:
6
6
@@ -32,7 +32,7 @@ The components from the following imports have been refactored:
32
32
The refactored components offer several benefits over the old implementations, including:
33
33
* Improved accessibility
34
34
* Better adherence to the Material Design spec
35
- * Faster adoption of future versions of the Material Design spec, due to being based on common
35
+ * Faster adoption of future versions of the Material Design spec, due to being based on common
36
36
infrastructure
37
37
38
38
## What has changed?
@@ -109,7 +109,7 @@ much as it can automatically.
109
109
#### Running a Partial Migration
110
110
111
111
Depending on the size and complexity of your application, you may want to migrate a single component
112
- (or small group of components) at a time, rather than all at once.
112
+ (or small group of components) at a time, rather than all at once.
113
113
TODO(wagnermaciel): Add details on this: script params, which components need to move together
114
114
115
115
You may also want to migrate your app one module at a time instead of all together. You can use both
@@ -133,7 +133,7 @@ TODO(amysorto): Can we have the schematic generate a CSV of TODOs that can be im
133
133
### 4. Verify Your Application
134
134
135
135
After running the migration and addressing the TODOs, manually verify that everything is working
136
- correctly.
136
+ correctly.
137
137
138
138
Run your tests and confirm that they pass. It's possible that your tests depended on internal DOM or
139
139
async timing details of the old component implementations and may need to be updated. If you find
@@ -166,7 +166,7 @@ DOM and CSS of the components, you may need to tweak some of your application's
166
166
167
167
@include mat .all-component-typographies ();
168
168
```
169
-
169
+
170
170
or individually for components your application uses:
171
171
172
172
``` scss
@@ -176,7 +176,7 @@ DOM and CSS of the components, you may need to tweak some of your application's
176
176
@include mat .card-typography ();
177
177
// ...
178
178
```
179
-
179
+
180
180
* Default typography levels defined by ` mat.define-typography-config ` have been updated to reflect
181
181
changes to the Material Design spec.
182
182
@@ -185,15 +185,15 @@ DOM and CSS of the components, you may need to tweak some of your application's
185
185
186
186
``` scss
187
187
@import ' @angular/material' as mat ;
188
-
188
+
189
189
$theme : mat .define-light-theme ((
190
190
color : ...
191
191
));
192
-
192
+
193
193
// Adds density level 0 styles
194
194
@include mat .all-component-themes ($theme );
195
195
```
196
-
196
+
197
197
If you prefer a different default density level, you can set it in your theme config:
198
198
199
199
``` scss
@@ -213,7 +213,7 @@ TODO(mmalerba): link to density docs once they exist.
213
213
214
214
* Accessibility: Icon buttons are now 48px instead of 40px.
215
215
216
- * Accessibility: Buttons have a slightly different hover/focus/active colors, improving contrast
216
+ * Accessibility: Buttons have a slightly different hover/focus/active colors, improving contrast
217
217
ratios.
218
218
219
219
* Flat buttons have a different padding than raised buttons (this is apparent if you manually apply
@@ -282,10 +282,10 @@ TODO(mmalerba): link to density docs once they exist.
282
282
pattern. This is the only variant that supports selection state for chips. This pattern aligns
283
283
with the filter chips pattern specified in the Material Design spec. This pattern should be used
284
284
when you want the user to select one or more values from a list of options.
285
-
285
+
286
286
* ` <mat-chip-grid> ` with ` <mat-chip-row> ` - this pattern should be used for any text input + chips
287
287
interaction.
288
-
288
+
289
289
* ` <mat-chip-set> ` with ` <mat-chip> ` - this variant has no accessibility pattern and assumes one
290
290
will be applied at the application level. This allows the application to implement a custom
291
291
accessibility pattern with the chips visuals.
@@ -301,8 +301,8 @@ TODO(mmalerba): link to density docs once they exist.
301
301
not use any of the directives like ` mat-dialog-content ` .
302
302
303
303
* ` mat-dialog-content ` uses the font-settings specified by the Material Design spec, which includes
304
- a rather roomy line-height. If you have an information-dense dialog that doesn't look good with
305
- these settings, you can avoid using ` <mat-dialog-content> ` and just use a div with custom padding,
304
+ a rather roomy line-height. If you have an information-dense dialog that doesn't look good with
305
+ these settings, you can avoid using ` <mat-dialog-content> ` and just use a div with custom padding,
306
306
or use custom typography settings that can be applied with the ` mat.mdc-dialog-typography ` mixin.
307
307
308
308
* The old dialog triggered an extra change detection, which may have masked change detection issues
@@ -326,7 +326,7 @@ TODO(mmalerba): link to density docs once they exist.
326
326
327
327
* The text inside ` <mat-hint> ` is larger and darker in order to meet W3C text guidelines.
328
328
329
- * While the previous form-field had a single directive for prefixes (` matPrefix ` ) and a single
329
+ * While the previous form-field had a single directive for prefixes (` matPrefix ` ) and a single
330
330
directive for suffixes (` matSuffix ` ), the MDC-based form-field distinguishes between text
331
331
prefix/suffixes which are baseline aligned with the input text, and icon prefix/suffixes which are
332
332
center aligned in the form-field. Use ` matTextPrefix ` or ` matTextSuffix ` to indicate a text
@@ -364,7 +364,7 @@ TODO(mmalerba): link to density docs once they exist.
364
364
directives:
365
365
* `matListItemTitle`
366
366
* `matListItemLine`
367
-
367
+
368
368
* Text outside of a `matListItemLine` (so-called "unscoped content") will result in an additional
369
369
line being acquired (as if the content was put into a line ).
370
370
@@ -374,16 +374,16 @@ TODO(mmalerba): link to density docs once they exist.
374
374
Second line
375
375
</mat-list-item>
376
376
```
377
-
377
+
378
378
* The amount of lines is automatically inferred. e.g. in the snippet above the list item will
379
379
acquire space for two lines. With the new API you can now set an explicit number of lines on the
380
380
` <mat-list-item> ` to activate wrapping.
381
381
382
382
``` html
383
383
<mat-list-item lines =" 3" >
384
384
<span matListItemTitle >Title</span >
385
- This will text will wrap into the third line. Space for three lines is acquired by the list
386
- item.
385
+ This text will wrap into the third line. Space for three lines is acquired by the
386
+ list item.
387
387
</mat-list-item >
388
388
```
389
389
@@ -396,7 +396,7 @@ TODO(mmalerba): link to density docs once they exist.
396
396
* ` matListAvatar ` is now ` matListItemAvatar `
397
397
398
398
* Lastly, also a new directive (` matListItemMeta ` ) is available to put content into the meta section
399
- of a list item (usually the end of the list item). Previously unscoped content in a list item was
399
+ of a list item (usually the end of the list item). Previously unscoped content in a list item was
400
400
put into the meta section.
401
401
402
402
* Recommended migration steps for common use of a list item:
@@ -412,7 +412,7 @@ TODO(mmalerba): link to density docs once they exist.
412
412
413
413
* If you have a piece of content such as an ` <img> ` that you want to use in place of a
414
414
` <mat-icon> ` use ` ngProjectAs="mat-icon" ` to project it into the icon slot.
415
-
415
+
416
416
* If you need your icon to appear at the end of the item (not officially supported by the spec)
417
417
you can wrap both the text and your icon in a span, e.g.
418
418
@@ -422,7 +422,7 @@ TODO(mmalerba): link to density docs once they exist.
422
422
<mat-icon >end_icon</mat-icon >
423
423
</span >
424
424
```
425
-
425
+
426
426
* The text in menu items wrap instead of being hidden with an ellipses.
427
427
428
428
### Option / Optgroup
0 commit comments