2
2
3
3
## What is theming?
4
4
5
- Angular Material's theming system lets you customize color and typography styles for components
5
+ Angular Material's theming system lets you customize color, typography, and density styles for components
6
6
in your application. The theming system is based on Google's
7
7
[ Material Design] [ material-design-theming ] specification.
8
8
@@ -86,7 +86,7 @@ $my-palette: mat.$indigo-palette;
86
86
87
87
## Themes
88
88
89
- A ** theme** is a collection of color and typography options. Each theme includes three palettes that
89
+ A ** theme** is a collection of color, typography, and density options. Each theme includes three palettes that
90
90
determine component colors:
91
91
92
92
* A ** primary** palette for the color that appears most frequently throughout your application
@@ -98,8 +98,8 @@ custom theme with Sass, or by importing a pre-built theme CSS file.
98
98
99
99
### Custom themes with Sass
100
100
101
- A ** theme file** is a Sass file that calls Angular Material Sass mixins to output color and
102
- typography CSS styles.
101
+ A ** theme file** is a Sass file that calls Angular Material Sass mixins to output color,
102
+ typography, and density CSS styles.
103
103
104
104
#### The ` core ` mixin
105
105
@@ -116,8 +116,9 @@ times will result in duplicate CSS in your application.
116
116
117
117
#### Defining a theme
118
118
119
- Angular Material represents a theme as a Sass map that contains your color and typography
120
- choices. For more about typography customization, see [ Angular Material Typography] [ mat-typography ] .
119
+ Angular Material represents a theme as a Sass map that contains your color, typography, and density
120
+ choices. See [ Angular Material Typography] [ mat-typography ] for an in-depth guide to customizing typography. See
121
+ [ Customizing density] [ #customizing-density ] below for details on adjusting component density.
121
122
122
123
Constructing the theme first requires defining your primary and accent palettes, with an optional
123
124
warn palette. The ` define-palette ` Sass function accepts a color palette, described in the
@@ -154,7 +155,9 @@ $my-theme: mat.define-light-theme((
154
155
primary: $my-primary ,
155
156
accent: $my-accent ,
156
157
warn: $my-warn ,
157
- )
158
+ ),
159
+ typography: mat .define-typography-config (),
160
+ density: 0 ,
158
161
));
159
162
```
160
163
@@ -163,11 +166,12 @@ $my-theme: mat.define-light-theme((
163
166
The ` core-theme ` Sass mixin emits prerequisite styles for common features used by multiple
164
167
components, such as ripples. This mixin must be included once per theme.
165
168
166
- Each Angular Material component has a "color" mixin that emits the component's color styles and
167
- a "typography" mixin that emits the component's typography styles.
169
+ Each Angular Material component has a mixin for each color , typography, and density. For example, ` MatButton ` declares
170
+ ` button-color ` , ` button-typography ` , and ` button-density ` . Each mixin emits only the styles corresponding to that
171
+ area of customization.
168
172
169
- Additionally, each component has a "theme" mixin that emits styles for both color and typography .
170
- This theme mixin will only emit color or typography styles if you provided a corresponding
173
+ Additionally, each component has a "theme" mixin that emits all styles that depend on the theme config .
174
+ This theme mixin only emits color, typography, or density styles if you provided a corresponding
171
175
configuration to ` define-light-theme ` or ` define-dark-theme ` .
172
176
173
177
Apply the styles for each of the components used in your application by including each of their
@@ -185,7 +189,8 @@ $my-theme: mat.define-light-theme((
185
189
color : (
186
190
primary: $my-primary ,
187
191
accent: $my-accent ,
188
- )
192
+ ),
193
+ density: 0 ,
189
194
));
190
195
191
196
// Emit theme-dependent styles for common features used across multiple components.
@@ -201,8 +206,8 @@ $my-theme: mat.define-light-theme((
201
206
202
207
As an alternative to listing every component that your application uses, Angular Material offers
203
208
Sass mixins that includes styles for all components in the library: ` all-component-colors ` ,
204
- ` all-component-typographies ` , and ` all-component-themes ` . These mixins behave the same as individual
205
- component mixins, except they emit styles for ` core-theme ` and _ all_ 35+ components in Angular
209
+ ` all-component-typographies ` , ` all-component-densitites ` , and ` all-component-themes ` . These mixins behave the same as
210
+ individual component mixins, except they emit styles for ` core-theme ` and _ all_ 35+ components in Angular
206
211
Material. Unless your application uses every single component, this will produce unnecessary CSS.
207
212
208
213
``` scss
@@ -217,7 +222,9 @@ $my-theme: mat.define-light-theme((
217
222
color : (
218
223
primary: $my-primary ,
219
224
accent: $my-accent ,
220
- )
225
+ ),
226
+ typography: mat .define-typography-config (),
227
+ density: 0 ,
221
228
));
222
229
223
230
@include mat .all-component-themes ($my-theme );
@@ -274,33 +281,33 @@ CSS rule declaration. See the [documentation for Sass mixins][sass-mixins] for f
274
281
275
282
@include mat .core ();
276
283
277
- // Define a light theme
278
- $light-primary : mat .define-palette (mat .$indigo-palette );
279
- $light-accent : mat .define-palette (mat .$pink-palette );
280
- $light-theme : mat .define-light-theme ((
284
+ // Define a dark theme
285
+ $dark-theme : mat .define-dark-theme ((
281
286
color : (
282
- primary: $light-primary ,
283
- accent: $light-accent ,
284
- )
287
+ primary: mat .define-palette (mat .$pink-palette ),
288
+ accent: mat .define-palette (mat .$blue-grey-palette ),
289
+ ),
290
+ // Only include `typography` and `density` in the default dark theme.
291
+ typography: mat .define-typography-config (),
292
+ density: 0 ,
285
293
));
286
294
287
- // Define a dark theme
288
- $dark-primary : mat .define-palette (mat .$pink-palette );
289
- $dark-accent : mat .define-palette (mat .$blue-grey-palette );
290
- $dark-theme : mat .define-dark-theme ((
295
+ // Define a light theme
296
+ $light-theme : mat .define-light-theme ((
291
297
color : (
292
- primary: $dark-primary ,
293
- accent: $dark-accent ,
294
- )
298
+ primary: mat . define-palette ( mat . $indigo-palette ) ,
299
+ accent: mat . define-palette ( mat . $pink-palette ) ,
300
+ ),
295
301
));
296
302
297
303
// Apply the dark theme by default
298
304
@include mat .core-theme ($dark-theme );
299
305
@include mat .button-theme ($dark-theme );
300
306
301
- // Apply the light theme only when the `.my-light-theme` CSS class is applied
302
- // to an ancestor element of the components (such as `body`).
303
- .my-light-theme {
307
+ // Apply the light theme only when the user prefers light themes.
308
+ @media (prefers-color-scheme : light ) {
309
+ // Use the `-color` mixins to only apply color styles without reapplying the same
310
+ // typography and density styles.
304
311
@include mat .core-color ($light-theme );
305
312
@include mat .button-color ($light-theme );
306
313
}
@@ -318,7 +325,7 @@ file. The approach for this loading depends on your application.
318
325
### Application background color
319
326
320
327
By default, Angular Material does not apply any styles to your DOM outside
321
- of its own components. If you want to set your application's background color
328
+ its own components. If you want to set your application's background color
322
329
to match the components' theme, you can either:
323
330
1 . Put your application's main content inside ` mat-sidenav-container ` , assuming you're using ` MatSidenav ` , or
324
331
2 . Apply the ` mat-app-background ` CSS class to your main content root element (typically ` body ` ).
@@ -375,6 +382,38 @@ $my-palette: mat.define-palette(mat.$indigo-palette);
375
382
}
376
383
```
377
384
385
+ ## Customizing density
386
+
387
+ Angular Material's density customization is based on the
388
+ [ Material Design density guidelines] ( https://m2.material.io/design/layout/applying-density.html ) . This system
389
+ defines a scale where zero represents the default density. You can decrement the number for _ more density_ and increment
390
+ the number for _ less density_ .
391
+
392
+ The density system is based on a * density scale* . The scale starts with the
393
+ default density of ` 0 ` . Each whole number step down (` -1 ` , ` -2 ` , etc.) reduces
394
+ the affected sizes by ` 4px ` , down to the minimum size necessary for a component to render coherently.
395
+
396
+ Components that appear in task-based or pop-up contexts, such as ` MatDatepicker ` , don't change their size via the
397
+ density system. The [ Material Design density guidance] ( https://m2.material.io/design/layout/applying-density.html )
398
+ explicitly discourages increasing density for such interactions because they don't compete for space in the
399
+ application's layout.
400
+
401
+ You can apply custom density setting to the entire library or to individual components using their density Sass mixins.
402
+
403
+ ``` scss
404
+ // You can set a density setting in your theme to apply to all components.
405
+ $dark-theme : mat .define-dark-theme ((
406
+ color : ...,
407
+ typography: ...,
408
+ density: -2 ,
409
+ ));
410
+
411
+ // Or you can selectively apply the Sass mixin to affect only specific parts of your application.
412
+ .the-dense-zone {
413
+ @include mat .button-density (-1 );
414
+ }
415
+ ```
416
+
378
417
## Strong focus indicators
379
418
380
419
By default, most components indicate browser focus by changing their background color as described
@@ -464,10 +503,16 @@ the CSS in each shadow root, or by using [Constructable Stylesheets][constructab
464
503
[ shadow-dom ] : https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM
465
504
[ constructable-css ] : https://developers.google.com/web/updates/2019/02/constructable-stylesheets
466
505
506
+ ## User preference media queries
507
+
508
+ Angular Material does not apply styles based on user preference media queries, such as ` prefers-color-scheme `
509
+ or ` prefers-contrast ` . Instead, Angular Material's Sass mixins give you the flexibility to
510
+ apply theme styles to based on the conditions that make the most sense for your users. This may mean using media
511
+ queries directly or reading a saved user preference.
512
+
467
513
## Style customization outside the theming system
468
514
469
- Angular Material supports customizing color and typography as outlined in this document. Angular
515
+ Angular Material supports customizing color, typography, and density as outlined in this document. Angular
470
516
strongly discourages, and does not directly support, overriding component CSS outside the theming
471
517
APIs described above. Component DOM structure and CSS classes are considered private implementation
472
518
details that may change at any time.
473
-
0 commit comments