Skip to content

Commit c5afe36

Browse files
jelbournamysorto
authored andcommitted
docs(material/theming): update guide for density (#25975)
(cherry picked from commit 253a3b3)
1 parent 02d122a commit c5afe36

File tree

1 file changed

+80
-35
lines changed

1 file changed

+80
-35
lines changed

guides/theming.md

Lines changed: 80 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## What is theming?
44

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
66
in your application. The theming system is based on Google's
77
[Material Design][material-design-theming] specification.
88

@@ -86,7 +86,7 @@ $my-palette: mat.$indigo-palette;
8686

8787
## Themes
8888

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
9090
determine component colors:
9191

9292
* 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.
9898

9999
### Custom themes with Sass
100100

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.
103103

104104
#### The `core` mixin
105105

@@ -116,8 +116,9 @@ times will result in duplicate CSS in your application.
116116

117117
#### Defining a theme
118118

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.
121122

122123
Constructing the theme first requires defining your primary and accent palettes, with an optional
123124
warn palette. The `define-palette` Sass function accepts a color palette, described in the
@@ -154,7 +155,9 @@ $my-theme: mat.define-light-theme((
154155
primary: $my-primary,
155156
accent: $my-accent,
156157
warn: $my-warn,
157-
)
158+
),
159+
typography: mat.define-typography-config(),
160+
density: 0,
158161
));
159162
```
160163

@@ -163,11 +166,12 @@ $my-theme: mat.define-light-theme((
163166
The `core-theme` Sass mixin emits prerequisite styles for common features used by multiple
164167
components, such as ripples. This mixin must be included once per theme.
165168

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.
168172

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
171175
configuration to `define-light-theme` or `define-dark-theme`.
172176

173177
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((
185189
color: (
186190
primary: $my-primary,
187191
accent: $my-accent,
188-
)
192+
),
193+
density: 0,
189194
));
190195

191196
// Emit theme-dependent styles for common features used across multiple components.
@@ -201,8 +206,8 @@ $my-theme: mat.define-light-theme((
201206

202207
As an alternative to listing every component that your application uses, Angular Material offers
203208
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
206211
Material. Unless your application uses every single component, this will produce unnecessary CSS.
207212

208213
```scss
@@ -217,7 +222,9 @@ $my-theme: mat.define-light-theme((
217222
color: (
218223
primary: $my-primary,
219224
accent: $my-accent,
220-
)
225+
),
226+
typography: mat.define-typography-config(),
227+
density: 0,
221228
));
222229

223230
@include mat.all-component-themes($my-theme);
@@ -274,33 +281,33 @@ CSS rule declaration. See the [documentation for Sass mixins][sass-mixins] for f
274281

275282
@include mat.core();
276283

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((
281286
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,
285293
));
286294

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((
291297
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+
),
295301
));
296302

297303
// Apply the dark theme by default
298304
@include mat.core-theme($dark-theme);
299305
@include mat.button-theme($dark-theme);
300306

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.
304311
@include mat.core-color($light-theme);
305312
@include mat.button-color($light-theme);
306313
}
@@ -318,7 +325,7 @@ file. The approach for this loading depends on your application.
318325
### Application background color
319326

320327
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
322329
to match the components' theme, you can either:
323330
1. Put your application's main content inside `mat-sidenav-container`, assuming you're using `MatSidenav`, or
324331
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);
375382
}
376383
```
377384

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+
378417
## Strong focus indicators
379418

380419
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
464503
[shadow-dom]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM
465504
[constructable-css]: https://developers.google.com/web/updates/2019/02/constructable-stylesheets
466505

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+
467513
## Style customization outside the theming system
468514

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
470516
strongly discourages, and does not directly support, overriding component CSS outside the theming
471517
APIs described above. Component DOM structure and CSS classes are considered private implementation
472518
details that may change at any time.
473-

0 commit comments

Comments
 (0)