Skip to content

Commit 3c538c0

Browse files
mmalerbammalerba
committed
docs(material/theming): Update docs on accessing theme values (#28002)
(cherry picked from commit f1bf12f)
1 parent 5c7aa64 commit 3c538c0

File tree

3 files changed

+143
-102
lines changed

3 files changed

+143
-102
lines changed

‎guides/theming-your-components.md

Lines changed: 137 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -11,46 +11,149 @@ customize components. Angular Material provides APIs for reading values from thi
1111

1212
### Reading color values
1313

14-
To read color values from a theme, you can use the `get-color-config` Sass function. This function
15-
returns a Sass map containing the theme's primary, accent, and warn palettes, as well as a flag
16-
indicating whether dark mode is set.
14+
To read color values from a theme, you can use the `get-theme-color` Sass function. This function
15+
supports reading colors for both the app color palettes (primary, accent, and warn), as well as the
16+
foreground and background palettes. `get-theme-color` takes three arguments: The theme to read from,
17+
the name of the palette, and the name of the color.
18+
19+
Each of the color palettes (primary, accent, and warn) supports reading the following named colors:
20+
21+
| Color Name | Description |
22+
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
23+
| default | The default color from this palette |
24+
| lighter | A lighter version of the color for this palette |
25+
| darker | A darker version of the color for this palette |
26+
| text | The text color for this palette |
27+
| default-contrast | A color that stands out against the this palette's default color |
28+
| lighter-contrast | A color that stands out against the this palette's lighter color |
29+
| darker-contrast | A color that stands out against the this palette's darker color |
30+
| [hue] | The [hue] color for the palette.<br />[hue] can be one of: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, A100, A200, A400, A700 |
31+
| [hue]-contrast | A color that stands out against the [hue] color for the palette.<br />[hue] can be one of: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, A100, A200, A400, A700 |
32+
33+
The background palette supports reading the following named colors:
34+
35+
| Color Name | Description |
36+
|--------------------------|----------------------------------------------------|
37+
| status-bar | The background color for a status bar |
38+
| app-bar | The background color for an app bar |
39+
| background | The background color for the app |
40+
| hover | The background color of a hover overlay |
41+
| card | The background color of a card |
42+
| dialog | The background color of a dialog |
43+
| raised-button | The background color of a raised button |
44+
| selected-button | The background color of a selected button |
45+
| selected-disabled-button | The background color of a selected disabled button |
46+
| disabled-button | The background color of a disabled button |
47+
| focused-button | The background color of a focused button |
48+
| disabled-button-toggle | The background color of a disabled button toggle |
49+
| unselected-chip | The background color of an unselected chip |
50+
| disabled-list-option | The background color of a disabled list option |
51+
| tooltip | The background color of a tooltip |
52+
53+
The foreground palette supports reading the following named colors:
54+
55+
| Color name | Description |
56+
|-------------------|----------------------------------------------------------------------------------------------------------|
57+
| base | The base foreground color, can be used to for color mixing or creating a custom opacity foreground color |
58+
| divider | The color of a divider |
59+
| dividers | (Alternate name for divider) |
60+
| disabled-text | The color for disabled text |
61+
| disabled | (Alternate name for disabled-text) |
62+
| disabled-button | The color for disabled button text |
63+
| elevation | The color elevation shadows |
64+
| hint-text | The color for hint text |
65+
| secondary-text | The color for secondary text |
66+
| icon | The color for icons |
67+
| icons | (Alternate name for icon) |
68+
| text | The color for text | |
69+
70+
In addition to reading particular colors, you can use the `get-theme-type` Sass function to
71+
determine the type of theme (either light or dark). This function takes a single argument, the
72+
theme, and returns either `light` or `dark`.
73+
74+
See the below example of reading some colors from a theme:
1775

1876
```scss
19-
@use 'sass:map';
20-
@use '@angular/material' as mat;
77+
$theme: mat.define-dark-theme(...);
78+
79+
$primary-default: mat.get-theme-color($theme, primary, default);
80+
$accent-a100: mat.get-theme-color($theme, accent, A100);
81+
$warn-500-contrast: mat.get-theme-color($theme, warn, 500-contrast);
82+
$foreground-text: mat.get-theme-color($theme, foreground, text);
83+
$background-card: mat.get-theme-color($theme, background, card);
84+
$type: mat.get-theme-type($theme);
85+
$custom-background: if($type == dark, #030, #dfd);
86+
```
2187

22-
$primary: mat.define-palette(mat.$indigo-palette);
23-
$accent: mat.define-palette(mat.$pink-palette);
24-
$warn: mat.define-palette(mat.$red-palette);
88+
### Reading typography values
2589

26-
$theme: mat.define-light-theme((
27-
color: (primary: $primary, accent: $accent, warn: $warn),
28-
));
90+
To read typography values from a theme, you can use the `get-theme-typography` Sass function. This
91+
function supports reading typography properties from the typography levels defined in the theme.
92+
There are two ways to call the function.
93+
94+
The first way to call it is by passing just the theme and the typography level to get a shorthand
95+
`font` property based on the settings for that level. (Note: `letter-spacing` cannot be expressed in
96+
the `font` shorthand, so it must be applied separately).
97+
98+
The second way to call it is by passing the theme, typography level, and the specific font property
99+
you want: `font-family`, `font-size`, `font-weight`, `line-height`, or `letter-spacing`.
29100

30-
$color-config: mat.get-color-config($theme);
31-
$primary-palette: map.get($color-config, 'primary');
32-
$accent-palette: map.get($color-config, 'accent');
33-
$warn-palette: map.get($color-config, 'warn');
34-
$is-dark-theme: map.get($color-config, 'is-dark');
101+
The available typography levels are:
102+
103+
| Name | Description |
104+
|------------|----------------------------------------------------------------------|
105+
| headline-1 | One-off header, usually at the top of the page (e.g. a hero header). |
106+
| headline-2 | One-off header, usually at the top of the page (e.g. a hero header). |
107+
| headline-3 | One-off header, usually at the top of the page (e.g. a hero header). |
108+
| headline-4 | One-off header, usually at the top of the page (e.g. a hero header). |
109+
| headline-5 | Section heading corresponding to the `<h1>` tag. |
110+
| headline-6 | Section heading corresponding to the `<h2>` tag. |
111+
| subtitle-1 | Section heading corresponding to the `<h3>` tag. |
112+
| subtitle-2 | Section heading corresponding to the `<h4>` tag. |
113+
| body-1 | Base body text. |
114+
| body-2 | Secondary body text. |
115+
| caption | Smaller body and hint text. |
116+
| button | Buttons and anchors. |
117+
118+
See the below example of reading some typography settings from a theme:
119+
120+
```scss
121+
$theme: mat.define-dark-theme(...);
122+
123+
body {
124+
font: mat.get-theme-typography($theme, body-1);
125+
letter-spacing: mat.get-theme-typography($theme, body-1, letter-spacing);
126+
}
35127
```
36128

37-
See the [theming guide][theme-read-hues] for more information on reading hues from palettes.
129+
### Reading density values
38130

39-
[theme-read-hues]: https://material.angular.io/guide/theming#reading-hues-from-palettes
131+
To read the density scale from a theme, you can use the `get-theme-density` Sass function. This
132+
function takes a theme and returns the density scale (0, -1, -2, -3, -4, or -5).
40133

41-
### Reading typography values
134+
See the below example of reading the density scale from a theme:
135+
136+
```scss
137+
$theme: mat.define-dark-theme(...);
42138

43-
To read typography values from a theme, you can use the `get-typography-config` Sass function. See
44-
the [Typography guide][typography-config] for more information about the typography config data
45-
structure and for APIs for reading values from this config.
139+
$density-scale: mat.get-theme-desity($theme);
140+
```
46141

47-
[typography-config]: https://material.angular.io/guide/typography#typography-config
142+
### Checking what dimensions are configured for a theme
143+
144+
Depending on how a theme was created, it may not have configuration data for all theming dimensions
145+
(base, color, typography, density). You can check if a theme has a configuration for a particular
146+
dimension by calling the `theme-has` Sass function, passing the theme and the dimension to check.
147+
148+
See the below example of checking the configured dimensions for a theme:
48149

49150
```scss
50-
@use '@angular/material' as mat;
151+
$theme: mat.define-dark-theme(...);
51152

52-
$typography-config: mat.get-typography-config($theme);
53-
$my-font-family: mat.font-family($typography-config);
153+
$has-base: mat.theme-has($theme, base);
154+
$has-color: mat.theme-has($theme, color);
155+
$has-typography: mat.theme-has($theme, typography);
156+
$has-density: mat.theme-has($theme, density);
54157
```
55158

56159
## Separating theme styles
@@ -134,24 +237,16 @@ theme passed into the mixins.
134237
@use '@angular/material' as mat;
135238

136239
@mixin color($theme) {
137-
// Get the color config from the theme.
138-
$color-config: mat.get-color-config($theme);
139-
140-
// Get the primary color palette from the color-config.
141-
$primary-palette: map.get($color-config, 'primary');
142-
143240
.my-carousel-button {
144241
// Read the 500 hue from the primary color palette.
145-
color: mat.get-color-from-palette($primary-palette, 500);
242+
color: mat.get-theme-color($theme, primary, 500);
146243
}
147244
}
148245

149246
@mixin typography($theme) {
150-
// Get the typography config from the theme.
151-
$typography-config: mat.get-typography-config($theme);
152-
153247
.my-carousel {
154-
font-family: mat.font-family($typography-config);
248+
// Get the headline font from the theme.
249+
font: mat.get-theme-typography($theme, headline-1);
155250
}
156251
}
157252
```
@@ -169,35 +264,25 @@ have a config specified.
169264
@use '@angular/material' as mat;
170265

171266
@mixin color($theme) {
172-
// Get the color config from the theme.
173-
$color-config: mat.get-color-config($theme);
174-
175-
// Get the primary color palette from the color-config.
176-
$primary-palette: map.get($color-config, 'primary');
177-
178267
.my-carousel-button {
179268
// Read the 500 hue from the primary color palette.
180-
color: mat.get-color-from-palette($primary-palette, 500);
269+
color: mat.get-theme-color($theme, primary, 500);
181270
}
182271
}
183272

184273
@mixin typography($theme) {
185-
// Get the typography config from the theme.
186-
$typography-config: mat.get-typography-config($theme);
187-
188274
.my-carousel {
189-
font-family: mat.font-family($typography-config);
275+
// Get the headline font from the theme.
276+
font: mat.get-theme-typography($theme, headline-1);
190277
}
191278
}
192279

193280
@mixin theme($theme) {
194-
$color-config: mat.get-color-config($theme);
195-
@if $color-config != null {
281+
@if mat.theme-has($theme, color) {
196282
@include color($theme);
197283
}
198284

199-
$typography-config: mat.get-typography-config($theme);
200-
@if $typography-config != null {
285+
@if mat.theme-has($theme, typography) {
201286
@include typography($theme);
202287
}
203288
}

‎guides/theming.md

Lines changed: 3 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -398,34 +398,10 @@ The example below shows how to customize the color of all buttons inside element
398398

399399
### Reading hues from palettes
400400

401-
You can use the `get-color-from-palette` function to get specific hues from a palette by their
402-
number identifier. You can also access the contrast color for a particular hue by suffixing the
403-
hue's number identifier with `-contrast`.
401+
It is possible to read colors from a theme for use in your own components. For more information
402+
about this see our guide on [Theming your own components][reading-colors].
404403

405-
```scss
406-
@use '@angular/material' as mat;
407-
408-
$my-palette: mat.define-palette(mat.$indigo-palette);
409-
410-
.my-custom-style {
411-
background: mat.get-color-from-palette($my-palette, 500);
412-
color: mat.get-color-from-palette($my-palette, '500-contrast');
413-
}
414-
```
415-
416-
You can also reference colors using the `"default"`, `"lighter"`, `"darker"`, and `"text"` colors
417-
passed to `define-palette`.
418-
419-
```scss
420-
@use '@angular/material' as mat;
421-
422-
$my-palette: mat.define-palette(mat.$indigo-palette);
423-
424-
.my-custom-darker-style {
425-
background: mat.get-color-from-palette($my-palette, 'darker');
426-
color: mat.get-color-from-palette($my-palette, 'darker-contrast');
427-
}
428-
```
404+
[reading-colors]: https://material.angular.io/guide/theming-your-components#reading-color-values
429405

430406
## Customizing density
431407

‎guides/typography.md

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -227,27 +227,7 @@ The following example demonstrates usage of the typography styles emitted by the
227227

228228
### Reading typography values from a config
229229

230-
You can read typography style values from a typography config via the following Sass functions. Each
231-
accepts a typography config and a level.
230+
It is possible to read typography properties from a theme for use in your own components. For more
231+
information about this see our guide on [Theming your own components][reading-typography].
232232

233-
| Function | Example usage |
234-
|------------------|------------------------------------------|
235-
| `font-size` | `mat.font-size($config, 'body-1');` |
236-
| `font-family` | `mat.font-family($config, 'body-1');` |
237-
| `font-weight` | `mat.font-weight($config, 'body-1');` |
238-
| `line-height` | `mat.line-height($config, 'body-1');` |
239-
| `letter-spacing` | `mat.letter-spacing($config, 'body-1');` |
240-
241-
Additionally, you can use the `typography-level` Sass mixin to directly emit the CSS styles for a
242-
given typography level.
243-
244-
```scss
245-
@use '@angular/material' as mat;
246-
247-
// Use the default configuration.
248-
$my-typography: mat.define-typography-config();
249-
250-
.some-class-name {
251-
@include mat.typography-level($my-typography, 'body-1');
252-
}
253-
```
233+
[reading-typography]: https://material.angular.io/guide/theming-your-components#reading-typography-values

0 commit comments

Comments
 (0)