docs-bug(THEMING): Theme config migration since v18

[rsi21]

Documentation Feedback

In our project we started using Material 3 theming since Angular 18.
We used for that the following mixins mat.define-theme, mat.define-light-theme, or mat.define-dark-theme.
In usage like:

@use '@angular/material' as mat;

$theme: mat.define-theme((
  color: (
    theme-type: dark,
    primary: mat.$violet-palette,
  ),
  typography: (
    brand-family: 'Comic Sans',
    bold-weight: 900
  ),
  density: (
    scale: -1
  )
));

But since Angular 19 and now Angular 20, we have in the documentation Here a comment indicating to still have a look to v18 documentation.

If your application depends on a version before v19, or if your application's theme is applied using a theme config created with mat.define-theme, mat.define-light-theme, or mat.define-dark-theme, then you can refer to the theming guides at [v18.material.angular.dev/guides](https://v18.material.angular.dev/guides).

Regarding that, several questions/clarifications will help a lot:

• the "old way" used since V18 is going to be deprecated ?
• we follow all release notes since v18, but didn't see anything explaining how to migrate to the new functions ?
• Is there a schematic available for that migration ?

Thanks for your help

Affected documentation page

https://material.angular.dev/guide/theming

[andrewseguin]

Thanks for the feedback about migrating - we should consider adding in a section for moving off theme configs.

The theme config approach won't be going anywhere, since it would be too much of a lift to tell people they have to change, but we would encourage everyone to switch off them if they are using M3 styles. Using mat.theme is a much nicer experience, enabling system variables and removing the need for calling any mixins, even for your app's custom components.

To switch, you should be able to simply append this call to your theme file:

html {
  mat.define-theme((
    color: (
      theme-type: dark,
      primary: mat.$violet-palette,
    ),
    typography: (
      brand-family: 'Comic Sans',
      bold-weight: 900
    ),
    density: (
      scale: -1
    )
  ));
}

This will define system variables that our components use as fallbacks. With those defined, you shouldn't need to call any Angular Material component theme mixins anymore. In your own component styles, I'd recommend using the system variables directly instead of the mat.get-color-from-theme sort of APIs. https://material.angular.dev/guide/system-variables