Skip to content

Commit 95660ad

Browse files
mmalerbammalerba
committed
docs: add an MDC migration guide
1 parent 04ea76c commit 95660ad

File tree

1 file changed

+217
-0
lines changed

1 file changed

+217
-0
lines changed

‎guides/v15-mdc-migration.md

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Migrating to MDC-based Angular Material Components
2+
3+
In Angular Material v15, many of the components have been rewritten to be based on the official
4+
[Material Design Components for Web (MDC)](https://github.com/material-components/material-components-web).
5+
The components in the following packages have been rewritten:
6+
* @angular/material/autocomplete
7+
* @angular/material/button
8+
* @angular/material/card
9+
* @angular/material/checkbox
10+
* @angular/material/chips
11+
* @angular/material/core
12+
* @angular/material/dialog
13+
* @angular/material/form-field
14+
* @angular/material/input
15+
* @angular/material/list
16+
* @angular/material/menu
17+
* @angular/material/paginator
18+
* @angular/material/progress-bar
19+
* @angular/material/progress-spinner
20+
* @angular/material/radio
21+
* @angular/material/select
22+
* @angular/material/slide-toggle
23+
* @angular/material/slider
24+
* @angular/material/snack-bar
25+
* @angular/material/table
26+
* @angular/material/tabs
27+
* @angular/material/tooltip
28+
29+
The rewritten components offer several benefits over the old implementations, including:
30+
* Improved accessibility
31+
* Better adherence to the Material Design spec
32+
* Faster adoption of future versions of the Material Design spec, due to being based on common
33+
infrastructure
34+
35+
## What has changed?
36+
37+
The new components have different internal DOM and CSS styles. However, the TypeScript APIs and
38+
component/directive selectors for the new components have been kept as close as possible to the old
39+
implementation. This makes it straightforward to migrate your app and get it running with the new
40+
components.
41+
42+
Due to the new DOM and CSS, you will likely find that some styles in your app need to be adjusted,
43+
particularly if your CSS is overriding styles on internal elements on any of the migrated
44+
components.
45+
46+
There are a few components with larger changes to their APIs that were necessary in order to
47+
integrate with MDC. These components include:
48+
* form-field
49+
* chips
50+
* slider
51+
* list
52+
53+
See below for a [detailed list of changes](#Detailed List of Changes) to be aware of for these and
54+
other components.
55+
56+
The old implementation of each new component is now deprecated, but still available under a "legacy"
57+
package. e.g. The old `mat-button` implementation can be used by importing the legacy button module.
58+
59+
```ts
60+
import {MatLegacyButtonModule} from '@angular/material/legacy-button';
61+
```
62+
63+
## How to Migrate
64+
65+
Migrating an existing app to use MDC based components is a tool-assisted migration. The Angular
66+
Material team has built schematics to handle as much of the work as possible. However, some manual
67+
effort will be needed.
68+
69+
You can reduce the amount of manual effort needed by ensuring that your app follows good practices
70+
before migrating.
71+
* Avoid overriding styles on internal Angular Material elements in your CSS as much as possible. If
72+
you find yourself frequently overriding styles on internal elements, consider using a component
73+
that is designed for more style customization, such as the ones available in the
74+
[Angular CDK](/cdk).
75+
* Use [component harnesses](./using-component-harnesses) to interact with Angular Material
76+
components in tests rather than probing internal elements, properties, or methods of the
77+
component. Using component harnesses makes your tests easier to understand and more robust to
78+
changes in Angular Material
79+
80+
### 1. Update to Angular Material v15
81+
82+
Angular Material now includes a schematic to help migrate pre-existing apps to use the new
83+
MDC-based components. To get started, upgrade your app to Angular Material 15.
84+
85+
```shell
86+
ng update @angular/components^15
87+
```
88+
89+
As part of this update, a schematic will run to automatically move your app to use the "legacy"
90+
packages containing the old component implementations. This provides a quick path to getting your
91+
app running on v15 with minimal manual changes.
92+
93+
### 2. Run the MDC Migration Script
94+
95+
After upgrading to v15, you can run the MDC Migration Script to switch from the legacy component
96+
implementations to the new MDC-based ones.
97+
98+
```shell
99+
ng generate # TODO(wagnermaciel): Insert command here.
100+
```
101+
102+
This command will update your app's TypeScript, CSS, and templates to the new implementations,
103+
updating as much as it can automatically.
104+
105+
#### Running a Partial Migration
106+
107+
Depending on the size and complexity of your app, you may want to migrate a single component (or
108+
small group of components) at a time, rather than all at once.
109+
TODO(wagnermaciel): Add details on this: script params, which components need to move together
110+
111+
You may also want to migrate your app one module at a time instead of all together. It is possible
112+
to use both the old implementation and new implementation in the same app, as long as they aren't
113+
used in the same module. TODO(wagnermaciel): Add detail on this: script params.
114+
115+
### 3. Check for TODOs left by the migration script.
116+
117+
In situations where the script is not able to automatically update your code, it will attempt to add
118+
comments for a human to follow up. These TODO comments follow a common format, so they can be easily
119+
identified.
120+
121+
```ts
122+
// TODO(wagnermaciel): Do we have a common format for all TODOs the script adds?
123+
```
124+
125+
To search for all comments left by the script, search for `TODO(...):` in your IDE, or use the
126+
following grep command.
127+
128+
```shell
129+
grep -lr --exclude-dir=node_modules "TODO(...):"
130+
```
131+
132+
### 4. Verify Your App
133+
134+
After running the migration and addressing the TODOs, manually verify that everything is working
135+
correctly.
136+
137+
Run your tests and confirm that they pass. It's possible that your tests depended on internal DOM or
138+
async timing details of the old component implementations and may need to be updated. If you find
139+
you need to update some tests, consider using [Component Harnesses](./using-component-harnesses) to
140+
make the tests more robust.
141+
142+
Run your app and verify that the new components look right. Due to the changes in internal DOM and
143+
CSS of the components, you may need to tweak some of your app's styles.
144+
145+
## Detailed List of Changes
146+
147+
### Library-wide Changes
148+
...
149+
150+
### Core CSS & Theming
151+
...
152+
153+
### Autocomplete
154+
...
155+
156+
### Button
157+
...
158+
159+
### Card
160+
...
161+
162+
### Checkbox
163+
...
164+
165+
### Chips
166+
...
167+
168+
### Dialog
169+
...
170+
171+
### Form Field
172+
...
173+
174+
### Input
175+
...
176+
177+
### List
178+
...
179+
180+
### Menu
181+
...
182+
183+
### Option
184+
...
185+
186+
### Paginator
187+
...
188+
189+
### Progress Bar
190+
...
191+
192+
### Progress Spinner
193+
...
194+
195+
### Radio
196+
...
197+
198+
### Select
199+
...
200+
201+
### Slide Toggle
202+
...
203+
204+
### Slider
205+
...
206+
207+
### Snack Bar
208+
...
209+
210+
### Table
211+
...
212+
213+
### Tabs
214+
...
215+
216+
### Tooltip
217+
...

0 commit comments

Comments
 (0)