docs-bug(Typography): It isn't clear how to customise Material 3 typography

[DzmVasileusky]

trafficstars

Documentation Feedback

Material 2 docs were pretty clear about how to customise typography.

@use '@angular/material' as mat;

$my-custom-level: mat.m2-define-typography-level(
  $font-family: Roboto,
  $font-weight: 400,
  $font-size: 1rem,
  $line-height: 1,
  $letter-spacing: normal,
);

$my-custom-typography-config: mat.m2-define-typography-config(
  $headline-1: mat.m2-define-typography-level(112px, 112px, 300, $letter-spacing: -0.05em),
  $headline-2: mat.m2-define-typography-level(56px, 56px, 400, $letter-spacing: -0.02em),
  $headline-3: mat.m2-define-typography-level(45px, 48px, 400, $letter-spacing: -0.005em),
  $headline-4: mat.m2-define-typography-level(34px, 40px, 400),
  $headline-5: mat.m2-define-typography-level(24px, 32px, 400),
  // ...
);

The current page called "Customizing Typography" doesn't have an information on how to customise it at all. It describes the usage only.

Migration guide isn't answering this question as well (https://material.angular.io/guide/material-2-theming#how-to-migrate-an-app-from-material-2-to-material-3).

Affected documentation page

https://material.angular.io/guide/theming#customizing-your-typography

[amysorto]

I agree this is an area of improvement, in the meantime the customizable fields are here: https://material.angular.io/guide/typography#configuring-typography. This is how you apply it to your theme: https://material.angular.io/guide/theming#defining-a-theme

[DzmVasileusky]

@amysorto But what about font-size, line-height, font-weight of specific typography levels? Why the customisation is so restricted? Can we really only choose font-family and font-weight for bold/medium now? Does it mean designers can't create their own typography now?

[DzmVasileusky]

Ok, I could customise it by overriding css vars at least like this:

:root {
    --mat-text-button-with-icon-horizontal-padding: 8px;
    --mdc-text-button-label-text-size: 16px;
}

however it is a partial customisation it would be better if we could customise it more globally

[crisbeto]

Another option could be to enable system variables for the theme and then only change the system variables.

[DzmVasileusky]

@crisbeto thanks, funny thing I didn't find docs on system variables on the official Angular material website but found it here https://angular-material.dev/articles/angular-material-theming-css-vars

Is it considered as a bad practice? Or are documents just not completed?

[crisbeto]

System variables are supported, we just haven't gotten around to writing a guide for them.

[DzmVasileusky]

@crisbeto thank you, having a guide for that would be really helpful

[shoff]

Couldn't agree more the M3 custom schematic documentation is just as bad if not worse. In the age of AI, there's no excuse for such horrible, incomplete and just flat wrong documentation. Either be professional, or stop publishing libraries with crap docs.

[shhdharmen]

I wrote an article about modifying typescales using CSS variables. You can read it here: https://angular-material.dev/articles/angular-material-18-typography

[CraigWarford]

The current generation is causing the font sizes to come in smaller than expected. The default size is expected to be right at 14px, but instead, --sys-label-large-size (for example) is set to 0.875rem, and works out to 12.5px instead of the 14px it used to be. So, everything looks small on the screen. Really don't want to go through and manually set all the variables for this...

[tasnim-reza]

This is what I'm using right now, though it lacks granular level control

@use "@angular/material" as mat;
@include mat.core();

$light-theme: mat.define-theme(
 (
  color: (
    theme-type: light,
    primary: $azure-palette,
    tertiary: $azure-palette
  ),
  typography: (
    brand-family: "your-font",
    plain-family: "your-font",
    bold-weight: 500,
    medium-weight: 400,
    regular-weight: 200
  ),
  density: (
    scale: 0
  )
 )
 );

[dee-cf]

@DzmVasileusky

I am in the exactly same situation. Could you please share how did you end up resolving this issue? How do you define your typography levels?

thanks

[dfa1234]

Let's start from the end. Let's say: I want my h1 to be bold. Currently it is not supported as it was before? According to the documentation

all what I see here is:

brand-family: "your-font",
plain-family: "your-font",
bold-weight: 500,
medium-weight: 400,
regular-weight: 200

What happened?

[dropddesigns]

Hopefully this helps someone out there in a similar situation as me.

None of the typography CSS selectors were coming back for any of the basic typography.

I had to add these two lines to my styles.scss and then the mat-typography class on

started working

$theme: mat.define-theme(); @include mat.typography-hierarchy($theme);

Update: I have found that the mat-typography styles coming back still return 'Roboto' as the font family, despite defining brand-family and plain-family in the @include mat.theme section of the html{} element in my SCSS.

I feel like $theme is a completely different theme to what I have defined but I am not sure how to access my theme definition as it is not a variable that I am aware of?

[dropddesigns]

A further update and some success but may still not be the complete answer as I haven't looked into updating the font-sizes, weights etc for the $levels as per

@mixin _m3-typography-level($theme, $selector-prefix, $level, $selectors, $margin: null) { #{_get-selector($selectors, $selector-prefix)} { // TODO(mmalerba): When we expose system tokens as CSS vars, we should change this to emit token // slots. font: inspection.get-theme-typography($theme, $level, font); letter-spacing: inspection.get-theme-typography($theme, $level, letter-spacing); @if $margin != null { margin: 0 0 $margin; } } }

I created a custom set of colour palettes using the 'Material 3 Theme schematic'

ng generate @angular/material:theme-color

I then set up my styles.scss as per the steps for 'Adaptive high contrast colors for adaptive themes' on: https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/theme-color/README.md

However, this provides the fonts for the Angular Material components but not .mat-typography.

I was trying to avoid any Material 2 based methods to create the theme i.e. mat.define-light-theme but in order to get this working, I have made a compromise.

The following will allow you to have all of the Material typography levels styled in your application.

$custom-typography: mat.define-theme(( typography: ( brand-family: 'Arial', plain-family: 'Verdana', ) ));

@include mat.typography-hierarchy($custom-typography);

[dropddesigns]

One more finding which I think is the final piece of the puzzle, updating the typography styles.

This is done by updating the --sys CSS variables (note: for me, mine seem to be prefixed with --mat-sys instead).

The variables are declared from this source file: node_modules/@angular/material/core/tokens/_m3-system.scss

You may find the following reference handy which is where the next piece of code comes from: https://angular-material.dev/articles/angular-material-18-typography

:root { --sys-display-large-size: 128px; --sys-display-large-line-height: 1.25; /* <h1> (and display-large) uses --sys-display-large, hence we also need to update that variable to see the changes */ --sys-display-large: 400 var(--sys-display-large-size) / var(--sys-display-large-line-height) Roboto, sans-serif }

[CraigWarford]

FWIW, the above solutions did not work for me for any Angular 18.x versions. But as of Angular 19 (I started with 19.2), the @include mat.typography-hierarchy($theme); is now working as expected. The --sys variables are properly generated now, just like the palette vars were with 18.x.

[hhsissi]

I don't know if this is going to help anyone, but here's a list of all system variables for typography: Funny thing is that in documentation for a card overrides, there's no mention of any of them. There's a title-text-size, but where does it come from ? no idea... It seems like each component has its own thing. I'm a bit lost here.

--mat-sys-body-small
--mat-sys-body-small-font
--mat-sys-body-small-line-height
--mat-sys-body-small-size
--mat-sys-body-small-tracking
--mat-sys-body-small-weight


--mat-sys-body-medium
--mat-sys-body-medium-font
--mat-sys-body-medium-line-height
--mat-sys-body-medium-size
--mat-sys-body-medium-tracking
--mat-sys-body-medium-weight


--mat-sys-body-large
--mat-sys-body-large-font
--mat-sys-body-large-line-height
--mat-sys-body-large-size
--mat-sys-body-large-tracking
--mat-sys-body-large-weight


--mat-sys-display-small
--mat-sys-display-small-font
--mat-sys-display-small-line-height
--mat-sys-display-small-size
--mat-sys-display-small-tracking
--mat-sys-display-small-weight


--mat-sys-display-medium
--mat-sys-display-medium-font
--mat-sys-display-medium-line-height
--mat-sys-display-medium-size
--mat-sys-display-medium-tracking
--mat-sys-display-medium-weight


--mat-sys-display-large
--mat-sys-display-large-font
--mat-sys-display-large-line-height
--mat-sys-display-large-size
--mat-sys-display-large-tracking
--mat-sys-display-large-weight


--mat-sys-headline-small
--mat-sys-headline-small-font
--mat-sys-headline-small-line-height
--mat-sys-headline-small-size
--mat-sys-headline-small-tracking
--mat-sys-headline-small-weight


--mat-sys-headline-medium
--mat-sys-headline-medium-font
--mat-sys-headline-medium-line-height
--mat-sys-headline-medium-size
--mat-sys-headline-medium-tracking
--mat-sys-headline-medium-weight


--mat-sys-headline-large
--mat-sys-headline-large-font
--mat-sys-headline-large-line-height
--mat-sys-headline-large-size
--mat-sys-headline-large-tracking
--mat-sys-headline-large-weight


--mat-sys-label-small
--mat-sys-label-small-font
--mat-sys-label-small-line-height
--mat-sys-label-small-size
--mat-sys-label-small-tracking
--mat-sys-label-small-weight


--mat-sys-label-medium
--mat-sys-label-medium-font
--mat-sys-label-medium-line-height
--mat-sys-label-medium-size
--mat-sys-label-medium-tracking
--mat-sys-label-medium-weight


--mat-sys-label-large
--mat-sys-label-large-font
--mat-sys-label-large-line-height
--mat-sys-label-large-size
--mat-sys-label-large-tracking
--mat-sys-label-large-weight


--mat-sys-title-small
--mat-sys-title-small-font
--mat-sys-title-small-line-height
--mat-sys-title-small-size
--mat-sys-title-small-tracking
--mat-sys-title-small-weight


--mat-sys-title-medium
--mat-sys-title-medium-font
--mat-sys-title-medium-line-height
--mat-sys-title-medium-size
--mat-sys-title-medium-tracking
--mat-sys-title-medium-weight


--mat-sys-title-large
--mat-sys-title-large-font
--mat-sys-title-large-line-height
--mat-sys-title-large-size
--mat-sys-title-large-tracking
--mat-sys-title-large-weight

[olafvanv]

I don't know if this is going to help anyone, but here's a list of all system variables for typography: Funny thing is that in documentation for a card overrides, there's no mention of any of them. There's a title-text-size, but where does it come from ? no idea... It seems like each component has its own thing. I'm a bit lost here.

The page https://material.angular.dev/components/card/styling does show the system tokens the component tokens are based on. So in your example title-text-size is based on --mat-sys-title-large-size.

I think the only way to go for now is to override these system variables, as described on https://material.angular.dev/guide/system-variables:

html {
  mat.theme-overrides((
    large-text-size: 2rem,
    etc...
  ))
}