angular · amysorto · Nov 18, 2024 · Dec 9, 2024 · Dec 13, 2024
@@ -35,7 +35,7 @@ The `ng add` command will additionally perform the following actions:
 
 * Add project dependencies to `package.json`
 * Add the Roboto font to your `index.html`
-* Add the Material Design icon font to your `index.html`
+* Add the Material Symbols icon font to your `index.html`
 * Add a few global CSS styles to:
   * Remove margins from `body`
   * Set `height: 100%` on `html` and `body`
@@ -48,7 +48,7 @@ You're done! Angular Material is now configured to be used in your application.
 Let's display a slide toggle component in your app and verify that everything works.
 
 You need to import the `MatSlideToggleModule` that you want to display by adding the following lines to
-your standalone component's imports, or otherwise your component's `NgModule`. 
+your standalone component's imports, or otherwise your component's `NgModule`.
 
 ```ts
 import { MatSlideToggleModule } from '@angular/material/slide-toggle';

@@ -22,13 +22,16 @@ In case you just want to install the `@angular/cdk`, there are also schematics f
 ng add @angular/cdk
 ```
 
-The Angular Material `ng add` schematic helps you set up an Angular CLI project that uses Material. Running `ng add` will:
+The Angular Material `ng add` schematic helps you set up an Angular CLI project that uses Material.
+See the [`getting started guide](./getting-started#install-angular-material) for more information.
 
-- Ensure [project dependencies](./getting-started#step-1-install-angular-material-angular-cdk-and-angular-animations) are placed in `package.json`
-- Enable the [BrowserAnimationsModule](./getting-started#step-2-configure-animations) in your app module
+Running `ng add` will:
+
+- Ensure project dependencies are placed in `package.json`
+- Enable the BrowserAnimationsModule in your app module
 - Add either a prebuilt theme or a custom theme
 - Add Roboto fonts to your `index.html`
-- Add the [Material Icon font](./getting-started#step-6-optional-add-material-icons) to your `index.html`
+- Add the Material Symbols font to your `index.html`
 - Add global styles to
   - Remove margins from `body`
   - Set `height: 100%` on `html` and `body`

@@ -8,7 +8,7 @@
   <link rel="icon" type="image/x-icon" href="favicon.ico">
   <link rel="preconnect" href="https://fonts.gstatic.com">
   <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
-  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined" rel="stylesheet">
 </head>
 <body class="mat-typography">
   <app-root></app-root>

@@ -1,10 +1,10 @@
 {
   "$schema": "./node_modules/@angular-devkit/schematics/collection-schema.json",
   "schematics": {
-    "migration-v19": {
-      "version": "19.0.0-0",
-      "description": "Updates the Angular CDK to v19",
-      "factory": "./ng-update/index#updateToV19"
+    "migration-v20": {
+      "version": "20.0.0-0",
+      "description": "Updates the Angular CDK to v20",
+      "factory": "./ng-update/index#updateToV20"
     },
     "ng-post-update": {
       "description": "Prints out results after ng-update.",

@@ -14,9 +14,9 @@ import {createMigrationSchematicRule, NullableDevkitMigration} from './devkit-mi
 const cdkMigrations: NullableDevkitMigration[] = [];
 
 /** Entry point for the migration schematics with target of Angular CDK 18.0.0 */
-export function updateToV19(): Rule {
+export function updateToV20(): Rule {
   return createMigrationSchematicRule(
-    TargetVersion.V19,
+    TargetVersion.V20,
     cdkMigrations,
     cdkUpgradeData,
     onMigrationComplete,

@@ -15,7 +15,7 @@ import {UpgradeData} from '../upgrade-data';
  * instances of outdated Angular CDK API that can't be migrated automatically.
  */
 export class MiscTemplateMigration extends Migration<UpgradeData> {
-  // There are currently no migrations for V19 deprecations.
+  // There are currently no migrations for V20 deprecations.
   enabled = false;
 
   override visitTemplate(template: ResolvedResource): void {}

@@ -10,7 +10,7 @@
 
 // tslint:disable-next-line:prefer-const-enum
 export enum TargetVersion {
-  V19 = 'version 19',
+  V20 = 'version 20',
 }
 
 /**

@@ -7,7 +7,7 @@
   <base href="/">
 
   <link rel="preconnect" href="https://fonts.gstatic.com">
-  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined" rel="stylesheet">
   <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap" rel="stylesheet">
   <link href="theme.css" rel="stylesheet">
 </head>

@@ -145,10 +145,10 @@ export class MatIconRegistry implements OnDestroy {
 
   /**
    * The CSS classes to apply when an `<mat-icon>` component has no icon name, url, or font
-   * specified. The default 'material-icons' value assumes that the material icon font has been
-   * loaded as described at https://google.github.io/material-design-icons/#icon-font-for-the-web
+   * specified. The default 'material-symbols-outlined' value assumes that the material icon font
+   * has been loaded as described at https://google.github.io/material-design-icons/#icon-font-for-the-web
    */
-  private _defaultFontSetClass = ['material-icons', 'mat-ligature-font'];
+  private _defaultFontSetClass = ['material-symbols-outlined', 'mat-ligature-font'];
 
   constructor(
     @Optional() private _httpClient: HttpClient,

@@ -17,14 +17,13 @@ Some fonts are designed to show icons by using
 component.
 
 By default, `<mat-icon>` expects the
-[Material icons font](https://google.github.io/material-design-icons/#icon-font-for-the-web).
+[Material Symbols](https://developers.google.com/fonts/docs/material_symbols#use_in_web).
 (You will still need to include the HTML to load the font and its CSS, as described in the link).
 
-You can specify a different font, such as Material's latest icons,
-[Material Symbols](https://fonts.google.com/icons), by setting the `fontSet` input to either the
-CSS class to apply to use the desired font, or to an alias previously registered with
-`MatIconRegistry.registerFontClassAlias`. Alternatively you can set the default for all
-your application's icons using `MatIconRegistry.setDefaultFontSetClass`.
+You can specify a different font, set the `fontSet` input to either the CSS class to apply to the
+desired font, or to an alias previously registered with `MatIconRegistry.registerFontClassAlias`.
+Alternatively you can set the default for all your application's icons using
+`MatIconRegistry.setDefaultFontSetClass`.
 
 ### Font icons with CSS
 

@@ -122,7 +122,7 @@ describe('MatIcon', () => {
       'mat-icon',
       'mat-ligature-font',
       'mat-primary',
-      'material-icons',
+      'material-symbols-outlined',
       'notranslate',
     ]);
   });
@@ -141,7 +141,7 @@ describe('MatIcon', () => {
       'mat-icon',
       'mat-icon-no-color',
       'mat-ligature-font',
-      'material-icons',
+      'material-symbols-outlined',
       'notranslate',
     ]);
   });
@@ -178,7 +178,7 @@ describe('MatIcon', () => {
   });
 
   describe('Ligature icons', () => {
-    it('should add material-icons and mat-ligature-font class by default', () => {
+    it('should add material-symbols-outlined and mat-ligature-font class by default', () => {
       const fixture = TestBed.createComponent(IconWithLigature);
 
       const testComponent = fixture.componentInstance;
@@ -190,7 +190,7 @@ describe('MatIcon', () => {
         'mat-icon',
         'mat-icon-no-color',
         'mat-ligature-font',
-        'material-icons',
+        'material-symbols-outlined',
         'notranslate',
       ]);
     });
@@ -265,7 +265,7 @@ describe('MatIcon', () => {
       expect(icon.getAttribute('fontIcon')).toBe('house');
     });
 
-    it('should add material-icons and mat-ligature-font class by default', () => {
+    it('should add material-symbols-outlined and mat-ligature-font class by default', () => {
       const fixture = TestBed.createComponent(IconWithLigatureByAttribute);
 
       const testComponent = fixture.componentInstance;
@@ -277,7 +277,7 @@ describe('MatIcon', () => {
         'mat-icon',
         'mat-icon-no-color',
         'mat-ligature-font',
-        'material-icons',
+        'material-symbols-outlined',
         'notranslate',
       ]);
     });

@@ -61,7 +61,7 @@ export class FakeMatIconRegistry implements PublicApi<MatIconRegistry>, OnDestro
   }
 
   getDefaultFontSetClass() {
-    return ['material-icons'];
+    return ['material-symbols-outlined'];
   }
 
   getSvgIconFromUrl(): Observable<SVGElement> {

@@ -1,10 +1,10 @@
 {
   "$schema": "./node_modules/@angular-devkit/schematics/collection-schema.json",
   "schematics": {
-    "migration-v19": {
-      "version": "19.0.0-0",
-      "description": "Updates Angular Material to v19",
-      "factory": "./ng-update/index_bundled#updateToV19"
+    "migration-v20": {
+      "version": "20.0.0-0",
+      "description": "Updates Angular Material to v20",
+      "factory": "./ng-update/index_bundled#updateToV20"
     }
   }
 }
@@ -28,7 +28,7 @@ export function addFontsToIndex(options: Schema): Rule {
 
     const fonts = [
       'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap',
-      'https://fonts.googleapis.com/icon?family=Material+Icons',
+      'https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined',
     ];
 
     projectIndexFiles.forEach(indexFilePath => {

@@ -162,7 +162,7 @@ describe('ng-add schematic', () => {
       // the created links properly align with the existing HTML. Default CLI projects use an
       // indentation of two columns.
       expect(htmlContent).toContain(
-        '  <link href="https://fonts.googleapis.com/icon?family=Material+Icons"',
+        '  <link href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined"',
       );
       expect(htmlContent).toContain(
         '  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@' +

@@ -6,30 +6,72 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {Rule, SchematicContext} from '@angular-devkit/schematics';
+import {chain, Rule, SchematicContext, Tree} from '@angular-devkit/schematics';
 import {
+  appendHtmlElementToHead,
   createMigrationSchematicRule,
+  getProjectFromWorkspace,
+  getProjectIndexFiles,
+  getWorkspaceConfigGracefully,
   NullableDevkitMigration,
   TargetVersion,
 } from '@angular/cdk/schematics';
+import {getWorkspace} from '@schematics/angular/utility/workspace';
 
 import {materialUpgradeData} from './upgrade-data';
-import {MatCoreMigration} from './migrations/mat-core-removal';
-import {ExplicitSystemVariablePrefixMigration} from './migrations/explicit-system-variable-prefix';
-
-const materialMigrations: NullableDevkitMigration[] = [
-  MatCoreMigration,
-  ExplicitSystemVariablePrefixMigration,
-];
-
-/** Entry point for the migration schematics with target of Angular Material v19 */
-export function updateToV19(): Rule {
-  return createMigrationSchematicRule(
-    TargetVersion.V19,
-    materialMigrations,
-    materialUpgradeData,
-    onMigrationComplete,
-  );
+
+const materialMigrations: NullableDevkitMigration[] = [];
+
+/** Entry point for the migration schematics with target of Angular Material v20 */
+export function updateToV20(): Rule {
+  return chain([
+    createMigrationSchematicRule(
+      TargetVersion.V20,
+      materialMigrations,
+      materialUpgradeData,
+      onMigrationComplete,
+    ),
+    // Updating to the new Material Symbols isn't a migration within materialMigrations since
+    // the index files are never visited within the migration schematic rule. The
+    // migrate() function within the update-tool only visits files referenced in
+    // typescript files which excludes the index template files:
+    // https://github.com/angular/components/blob/main/src/cdk/schematics/update-tool/index.ts#L71.
+    updateIconFontToMaterialSymbolsRule(),
+  ]);
+}
+
+/**
+ * Finds the index files and adds the import for Material Symbols font if needed. As of v20,
+ * Material Symbols becomes the default font icon since Material Icons is deprecated. This
+ * rule ensures the Material Symbols font is imported for existing applications.
+ * @returns Rule that adds the import for the Material Symbols icon font to the index files
+ */
+function updateIconFontToMaterialSymbolsRule(): Rule {
+  return async (tree: Tree, context: SchematicContext) => {
+    const workspace = await getWorkspaceConfigGracefully(tree);
+    const projectNames = workspace!.projects.keys();
+
+    let indexFiles: string[] = [];
+    for (const projectName of projectNames) {
+      const project = getProjectFromWorkspace(await getWorkspace(tree), projectName);
+      indexFiles = [...indexFiles, ...getProjectIndexFiles(project)];
+    }
+
+    const materialSymbolsFont =
+      'https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined';
+    for (const indexFile of indexFiles) {
+      // Add Material Symbols font if not imported in index file. References to the deprecated
+      // Material Icons are not removed since some applications may have manual overrides in their
+      // component styles that still reference it.
+      if (!tree.read(indexFile)?.includes(materialSymbolsFont)) {
+        appendHtmlElementToHead(
+          tree,
+          indexFile,
+          `<link href="${materialSymbolsFont}" rel="stylesheet">`,
+        );
+      }
+    }
+  };
 }
 
 /** Function that will be called when the migration completed. */