diff --git a/CHANGELOG_ARCHIVE.md b/CHANGELOG_ARCHIVE.md index 3335305fe079..9de1841eee84 100644 --- a/CHANGELOG_ARCHIVE.md +++ b/CHANGELOG_ARCHIVE.md @@ -7297,7 +7297,7 @@ contains all of the components. Build tools such as [`rollup.js`](http://rollupj tree-shaking to eliminate the code for components that you aren't using. The addition of theming as also changed the directory structure for bringing the core css into your -application. See the new [theming guide](guides/theming.md) for more information. +application. See the new [theming guide](guides/theming-with-config) for more information. ### Features diff --git a/guides/customizing-component-styles.md b/guides/customizing-component-styles.md deleted file mode 100644 index 2b3e02b5717c..000000000000 --- a/guides/customizing-component-styles.md +++ /dev/null @@ -1,106 +0,0 @@ -# Customizing Angular Material component styles - -Angular Material supports customizing component styles via Sass API as described in the [theming -guide][]. This document provides guidance on defining custom CSS rules that directly style -Angular Material components. - -[theming guide]: https://material.angular.io/guide/theming - -## Targeting custom styles - -### Component host elements - -For any Angular Material component, you can safely define custom CSS for a component's host element -that affect the positioning or layout of that component, such as `margin`, `position`, `top`, -`left`, `transform`, and `z-index`. You should apply such styles by defining a custom CSS -class and applying that class to the component's host element. - -Avoid defining custom styles that would affect the size or internal layout of the component, such as -`padding`, `height`, `width`, or `overflow`. You can specify `display: none` to hide a component, -but avoid specifying any other `display` value. Overriding these properties can break components -in unexpected ways as the internal styles change between releases. - -### Internal component elements - -Avoid any custom styles or overrides on internal elements within a Angular Material components. -The DOM structure and CSS classes applied for each component may change at any time, causing custom -styles to break. - -## Applying styles to Angular Material components - -While Angular Material does not support defining custom styles or CSS overrides on components' -internal elements, you might choose to do this anyway. There are three points to consider while -customizing styles for Angular Material components: view encapsulation, CSS specificity, and -rendering location. - -### View encapsulation - -By default, Angular scopes component styles to exclusively affect that component's view. This means -that the styles you author affect only the elements directly within your component template. -Encapsulated styles do *not* affect elements that are children of other components within your -template. You can read more about view encapsulation in the -[Angular documentation](https://angular.dev/guide/components/styling#style-scoping). You may -also wish to review -[_The State of CSS in Angular_](https://blog.angular.io/the-state-of-css-in-angular-4a52d4bd2700) -on the Angular blog. - -#### Bypassing encapsulation - -Angular Material disables style encapsulation for all components in the library. However, the -default style encapsulation in your own components still prevents custom styles from leaking into -Angular Material components. - -If your component enables view encapsulation, your component styles will only -affect the elements explicitly defined in your template. To affect descendants of components used -in your template, you can use one of the following approaches: - -1. Define custom styles in a global stylesheet declared in the `styles` array of your `angular.json` -configuration file. -2. Disable view encapsulation for your component. This approach effectively turns your component -styles into global CSS. -3. Apply the deprecated `::ng-deep` pseudo-class to a CSS rule. Any CSS rule with `::ng-deep` -becomes a global style. [See the Angular documentation for more on `::ng-deep`][ng-deep]. - -All of these approaches involve creating global CSS that isn't affected by style encapsulation. -Global CSS affects all elements in your application. Global CSS class names may collide with class -names defined by components. Global CSS is often a source of hard-to-diagnose bugs and is generally -difficult to maintain. - -[ng-deep]: https://angular.dev/guide/components/styling#ng-deep - -### CSS specificity - -Each CSS declaration has a level of *specificity* based on the type and number of selectors used. -More specific styles take precedence over less specific styles. Angular Material generally attempts -to use the least specific selectors possible. However, Angular Material may change component style -specificity at any time, making custom overrides brittle and prone to breaking. - -You can read more about specificity and how it is calculated on the -[MDN web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity). - -### Rendering location - -Some Angular Material components render elements that are not direct DOM descendants of the -component's host element. In particular, overlay-based components such as `MatDialog`, `MatMenu`, -`MatTooltip`, etc. render into an overlay container element directly on the document body. Because -these components render elements outside of your application's components, component-specific styles -will not apply to these elements. You can define styles for these elements as global styles. - -#### Styling overlay components - -Overlay-based components have a `panelClass` property, or similar, that let you target the -overlay pane. The following example shows how to add an `outline` style with `MatDialog`. - -```scss -// Add this to your global stylesheet after including theme mixins. -.my-outlined-dialog { - outline: 2px solid purple; -} -``` - -```ts -this.dialog.open(MyDialogComponent, {panelClass: 'my-outlined-dialog'}) -``` - -You should always apply an application-specific prefix to global CSS classes to avoid naming -collisions. diff --git a/guides/duplicate-theming-styles.md b/guides/duplicate-theming-styles.md deleted file mode 100644 index c85973453dd8..000000000000 --- a/guides/duplicate-theming-styles.md +++ /dev/null @@ -1,88 +0,0 @@ -# Avoiding duplicated theming styles - -As explained in the [theming guide](./theming.md), a theme in Angular Material consists of -configurations for the `color`, `density` and `typography` systems. As some of these individual -systems have default configurations, some usage patterns may cause duplication in the CSS output. - -Below are examples of patterns that generate duplicative theme styles: - -**Example #1** - -```scss -@use '@angular/material' as mat; - -$light-theme: mat.define-light-theme((color: ...)); -$dark-theme: mat.define-dark-theme((color: ...)); - -// Generates styles for all systems configured in the theme. In this case, color styles -// and default density styles are generated. Density is in themes by default. -@include mat.all-component-themes($light-theme); - -.dark-theme { - // Generates styles for all systems configured in the theme. In this case, color styles - // and the default density styles are generated. **Note** that this is a problem because it - // means that density styles are generated *again*, even though only the color should change. - @include mat.all-component-themes($dark-theme); -} -``` - -To fix this, you can use the dedicated mixin for color styles for the `.dark-theme` -selector. Replace the `all-component-themes` mixin and include the dark theme using the -`all-component-colors` mixin. For example: - -```scss -@use '@angular/material' as mat; - -... -@include mat.all-component-themes($light-theme); - -.dark-theme { - // This mixin only generates the color styles now. - @include mat.all-component-colors($dark-theme); -} -``` - -Typography can also be configured via Sass mixin; see `all-component-typographies`. - -**Example #2** - -Theme styles could also be duplicated if individual theme mixins are used. For example: - -```scss -@use '@angular/material' as mat; - -@include mat.all-component-themes($my-theme); - -.my-custom-dark-button { - // This will also generate the default density styles again. - @include mat.button-theme($my-theme); -} -``` - -To avoid this duplication of styles, use the dedicated mixin for the color system and -extract the configuration for the color system from the theme. - -```scss -@use '@angular/material' as mat; - -.my-custom-dark-button { - // This will only generate the color styles for `mat-button`. - @include mat.button-color($my-theme); -} -``` - -## Disabling duplication warnings - -If your application intentionally duplicates styles, a global Sass variable can be -set to disable duplication warnings from Angular Material. For example: - -```scss -@use '@angular/material' as mat; - -mat.$theme-ignore-duplication-warnings: true; - -// Include themes as usual. -@include mat.all-component-themes($light-theme); - -... -``` diff --git a/guides/elevation.md b/guides/elevation.md deleted file mode 100644 index 8725fda6746e..000000000000 --- a/guides/elevation.md +++ /dev/null @@ -1,70 +0,0 @@ -# Applying Elevation - -[The Material Design specification][material-elevation] gives guidance on expressing elevation on -UI elements by adding shadows. Angular Material provides CSS classes and Sass mixins for adding -these shadows. - -[material-elevation]: https://material.io/design/environment/elevation.html - -## Elevation CSS classes - -The `core-theme` Sass mixin, described in the [theming guide][theming-guide], emits CSS classes for applying -elevation. These classes follow the pattern `mat-elevation-z#`, where `#` is the elevation number -you want, from 0 to 24. These predefined classes use the CSS `box-shadow` settings defined by the -Material Design specification. - -You can dynamically change elevation on an element by swapping elevation CSS classes. - -```html -
-``` - - - -[theming-guide]: https://material.angular.io/guide/theming#applying-a-theme-to-components - -## Elevation Sass mixins - -In addition to the predefined CSS classes, you can apply elevation styles using the `elevation` -Sass mixin. This mixin accepts a `$zValue` and an optional `$color`. The `$zValue` is a number from -0 to 24, representing the semantic elevation of the element, that controls the intensity of the -box-shadow. You can use the `$color` parameter to further customize the shadow appearance. - -```scss -@use '@angular/material' as mat; - -.my-class-with-default-shadow { - // Adds a shadow for elevation level 2 with default color and full opacity: - @include mat.elevation(2); -} - -.my-class-with-custom-shadow { - // Adds a shadow for elevation level 2 with color #e91e63 and 80% of the default opacity: - @include mat.elevation(2, #e91e63, 0.8); -} -``` - -### Overridable elevation - -When authoring a component, you may want to specify a default elevation that the component consumer -can override. You can accomplish this by using the `overridable-elevation` Sass mixin. This behaves -identically to the `elevation` mixin, except that the styles only apply when the element does not -have a CSS class matching the pattern `mat-elevation-z#`, as described in -[Elevation CSS classes](#elevation-css-classes) above. - -### Animating elevation - -You can use the `elevation-transition` mixin to add a transition when elevation changes. - -```scss -@use '@angular/material' as mat; - -.my-class { - @include mat.elevation-transition(); - @include mat.elevation(2); - - &:active { - @include mat.elevation(8); - } -} -``` diff --git a/guides/schematics.md b/guides/schematics.md index ec7787de4429..25d14101e6d9 100644 --- a/guides/schematics.md +++ b/guides/schematics.md @@ -26,7 +26,7 @@ The Angular Material `ng add` schematic helps you set up an Angular CLI project - Ensure [project dependencies](./getting-started#step-1-install-angular-material-angular-cdk-and-angular-animations) are placed in `package.json` - Enable the [BrowserAnimationsModule](./getting-started#step-2-configure-animations) in your app module -- Add either a [prebuilt theme](./theming#pre-built-themes) or a [custom theme](./theming#defining-a-custom-theme) +- Add either a prebuilt theme or a custom theme - Add Roboto fonts to your `index.html` - Add the [Material Icon font](./getting-started#step-6-optional-add-material-icons) to your `index.html` - Add global styles to diff --git a/guides/theming-your-components.md b/guides/theming-your-components.md deleted file mode 100644 index c8c304f85f14..000000000000 --- a/guides/theming-your-components.md +++ /dev/null @@ -1,247 +0,0 @@ -# Theme your own components with Angular Material's theming system - -You can use Angular Material's Sass-based theming system for your own custom components. - -**Note: The information on this page is specific to Material 3, for Material 2 -information on how to theme your components see the [Material 2 guide][material-2].** - -[material-2]: https://material.angular.io/guide/material-2-theming#theming-your-components - -## Reading values from a theme - -As described in the [theming guide][theme-map], a theme is a Sass map that contains style values to -customize components. Angular Material provides APIs for reading values from this data structure. - -[theme-map]: https://material.angular.io/guide/theming#defining-a-theme - -### Reading tonal palette colors - -To read a -[tonal palette color](https://m3.material.io/styles/color/system/how-the-system-works#3ce9da92-a118-4692-8b2c-c5c52a413fa6) -from the theme, use the `get-theme-color` function with three arguments: - -| Argument | Description | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `$theme` | The M3 theme to read from. | -| `$palette` | The name of the palette to read from. This can be any of the standard M3 palettes: | -| `$hue` | The hue number to read within the palette. This can be any of the standard hues: | - - - -### Reading color roles - -To read a [color role](https://m3.material.io/styles/color/roles), use `get-theme-color` with two -arguments: - -| Argument | Description | -| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `$theme` | The M3 theme to read from. | -| `$role` | The name of the color role. This can be any of the M3 color roles: | - - - -### Reading the theme type - -To read the theme type (`light` or `dark`), call `get-theme-type` with a single argument: - -| Argument | Description | -| -------- | -------------------------- | -| `$theme` | The M3 theme to read from. | - - -### Reading typescale properties - -To read a [typescale](https://m3.material.io/styles/typography/type-scale-tokens) property from the -theme, call `get-theme-typography` with three arguments: - -| Argument | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `$theme` | The M3 theme to read from. | -| `$level` | The typescale level. This can be any of the M3 typescale levels: | -| `$property` | The CSS font property to get a value for. This can be one of the following CSS properties: | - - - -### Reading the density scale - -To read the density scale (`0`, `-1`, `-2`, `-3`, `-4`, or `-5`) from the theme, call -`get-theme-density` with a single argument: - -| Argument | Description | -| -------- | -------------------------- | -| `$theme` | The M3 theme to read from. | - -### Checking what dimensions are configured for a theme - -Depending on how a theme was created, it may not have configuration data for all theming dimensions -(base, color, typography, density). You can check if a theme has a configuration for a particular -dimension by calling the `theme-has` Sass function, passing the theme and the dimension to check. - -See the below example of checking the configured dimensions for a theme: - -```scss -$theme: mat.define-theme(...); - -$has-base: mat.theme-has($theme, base); -$has-color: mat.theme-has($theme, color); -$has-typography: mat.theme-has($theme, typography); -$has-density: mat.theme-has($theme, density); -``` - -## Separating theme styles - -Angular Material components each have a Sass file that defines mixins for customizing -that component's color and typography. For example, `MatButton` has mixins for `button-color` and -`button-typography`. Each mixin emits all color and typography styles for that component, -respectively. - -You can mirror this structure in your components by defining your own mixins. These mixins -should accept an Angular Material theme, from which they can read color and typography values. You -can then include these mixins in your application along with Angular Material's own mixins. - -## Step-by-step example - -To illustrate participation in Angular Material's theming system, we can look at an example of a -custom carousel component. The carousel starts with a single file, `carousel.scss`, that contains -structural, color, and typography styles. This file is included in the `styleUrls` of the component. - -```scss -// carousel.scss - -.my-carousel { - display: flex; - font-family: serif; -} - -.my-carousel-button { - border-radius: 50%; - color: blue; -} -``` - -### Step 1: Extract theme-based styles to a separate file - -To change this file to participate in Angular Material's theming system, we split the styles into -two files, with the color and typography styles moved into mixins. By convention, the new file -name ends with `-theme`. Additionally, the file starts with an underscore (`_`), indicating that -this is a Sass partial file. See the [Sass documentation][sass-partials] for more information about -partial files. - -[sass-partials]: https://sass-lang.com/guide#topic-4 - -```scss -// carousel.scss - -.my-carousel { - display: flex; -} - -.my-carousel-button { - border-radius: 50%; -} -``` - -```scss -// _carousel-theme.scss - -@mixin color($theme) { - .my-carousel-button { - color: blue; - } -} - -@mixin typography($theme) { - .my-carousel { - font-family: serif; - } -} -``` - -### Step 2: Use values from the theme - -Now that theme theme-based styles reside in mixins, we can extract the values we need from the -theme passed into the mixins. - -```scss -// _carousel-theme.scss - -@use 'sass:map'; -@use '@angular/material' as mat; - -@mixin color($theme) { - .my-carousel-button { - // Read the 50 hue from the primary color palette. - color: mat.get-theme-color($theme, primary, 50); - } -} - -@mixin typography($theme) { - .my-carousel { - // Get the large headline font from the theme. - font: mat.get-theme-typography($theme, headline-large, font); - } -} -``` - -### Step 3: Add a theme mixin - -For convenience, we can add a `theme` mixin that includes both color and typography. -This theme mixin should only emit the styles for each color and typography, respectively, if they -have a config specified. - -```scss -// _carousel-theme.scss - -@use 'sass:map'; -@use '@angular/material' as mat; - -@mixin color($theme) { - .my-carousel-button { - // Read the 50 hue from the primary color palette. - color: mat.get-theme-color($theme, primary, 50); - } -} - -@mixin typography($theme) { - .my-carousel { - // Get the large headline font from the theme. - font: mat.get-theme-typography($theme, headline-large, font); - } -} - -@mixin theme($theme) { - @if mat.theme-has($theme, color) { - @include color($theme); - } - - @if mat.theme-has($theme, typography) { - @include typography($theme); - } -} -``` - -### Step 4: Include the theme mixin in your application - -Now that you've defined the carousel component's theme mixin, you can include this mixin along with -the other theme mixins in your application. - -```scss -@use '@angular/material' as mat; -@use './path/to/carousel-theme' as carousel; - -$my-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$red-palette, - ), - typography: ( - brand-family: 'Comic Sans', - bold-weight: 900, - ), -)); - -html { - @include mat.all-component-themes($my-theme); - @include carousel.theme($my-theme); -} -``` diff --git a/guides/theming.md b/guides/theming.md index c6d73ea35ebf..689836dab8b9 100644 --- a/guides/theming.md +++ b/guides/theming.md @@ -1,651 +1,469 @@ -# Theming Angular Material +# Theming -## What is theming? +Angular Material lets you customize the appearance of your components by +defining a custom theme. Angular Material’s theming system is inspired by +Google’s [Material Design](https://m3.material.io/styles). -Angular Material's theming system lets you customize base, color, typography, and density styles for components in your application. The theming system is based on Google's -[Material Design 3][material-design-theming] specification which is the latest -iteration of Google's open-source design system, Material Design. +This guide describes how to set up theming for your application using +Sass APIs introduced in Angular Material v19. -**For Material 2 specific documentation and how to update to Material 3, see the -[Material 2 guide][material-2].** +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.io/guides](https://v18.material.angular.io/guides). -This document describes the concepts and APIs for customizing colors. For typography customization, -see [Angular Material Typography][mat-typography]. For guidance on building components to be -customizable with this system, see [Theming your own components][theme-your-own]. +## Getting Started -[material-design-theming]: https://m3.material.io/ -[material-2]: https://material.angular.io/guide/material-2-theming -[mat-typography]: https://material.angular.io/guide/typography -[theme-your-own]: https://material.angular.io/guide/theming-your-components +Your application needs to have a [Sass](https://sass-lang.com) **theme file** +that includes Angular Material’s `mat.theme` mixin. -### Sass +The `mat.theme` mixin takes a map that defines color, typography, and density +values and outputs a set of CSS variables that control the component appearance +and layout. These variables are based on +[Design Tokens](https://m3.material.io/foundations/design-tokens/overview). -Angular Material's theming APIs are built with [Sass](https://sass-lang.com). This document assumes -familiarity with CSS and Sass basics, including variables, functions, and mixins. +The color variables are defined using the CSS color function +[light-dark](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) +so that your theme can switch between light and dark mode using the CSS property +[color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme). -### Custom themes with Sass +The following example theme file applies a violet color palette, Roboto font, +and standard density to the application’s Angular Material components. It +targets the `html` selector to ensure the CSS variables are applied across the +entire application. The `color-scheme` is explicitly set to `light dark` so that +the end user's system preferences are used to determine whether the application +appears in light or dark mode. -A **theme file** is a Sass file that calls Angular Material Sass mixins to output color, -typography, and density CSS styles. - -#### Defining a theme - -Angular Material represents a theme as a Sass map that contains your color, typography, and density -choices, as well as some base design system settings. - -The simplest usage of the API, `$theme: mat.define-theme()` defines a theme with default values. -However, `define-theme` allows you to configure the appearance of your -Angular Material app along three theming dimensions: color, typography, and density, by passing a -theme configuration object. The configuration object may have the following properties. - -| Property | Description | -| ------------ | --------------------------------------------------------------------------------------------------------------- | -| `color` | [Optional] A map of color options. See [customizing your colors](#customizing-your-colors) for details. | -| `typography` | [Optional] A map of typography options. See [customizing your typography](#customizing-your-typography) for details. | -| `density` | [Optional] A map of density options. See [customizing your density](#customizing-your-density) for details. | - - - -```scss -@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 - ) -)); -``` - -#### Customizing your colors - -The following aspects of your app's colors can be customized via the `color` property of the theme -configuration object (see the [M3 color spec](https://m3.material.io/styles/color/roles) to learn -more about these terms): - -| Color Property | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `theme-type` | [Optional] Specifies the type of theme, `light` or `dark`. The choice of a light versus a dark theme determines the background and foreground colors used throughout the components. | -| `primary` | [Optional] Specifies the palette to use for the app's primary color palette. (Note: the secondary, neutral, and neutral-variant palettes described in the M3 spec will be automatically chosen based on your primary palette, to ensure a harmonious color combination). | -| `tertiary` | [Optional] Specifies the palette to use for the app's tertiary color palette. | - -##### Pre-built themes - -Angular Material includes several pre-built theme CSS files, each with different palettes selected. -You can use one of these pre-built themes if you don't want to define a custom theme with Sass. - -| Theme | Light or dark? | Specification | -|------------------------|----------------|----------------------------------| -| `azure-blue.css` | Light | Material Design 3 | -| `rose-red.css` | Light | Material Design 3 | -| `cyan-orange.css` | Dark | Material Design 3 | -| `magenta-violet.css` | Dark | Material Design 3 | -| `deeppurple-amber.css` | Light | Material Design 2 | -| `indigo-pink.css` | Light | Material Design 2 | -| `pink-bluegrey.css` | Dark | Material Design 2 | -| `purple-green.css` | Dark | Material Design 2 | - -These files include the CSS for every component in the library. To include only the CSS for a subset -of components, you must use the Sass API detailed in [Defining a theme](#defining-a-theme) above. -You can [reference the source code for these pre-built themes](https://github.com/angular/components/blob/main/src/material/core/theming/prebuilt) to see examples of complete theme definitions. - -##### Pre-defined palettes - -The pre-built themes are based on a set of pre-defined palettes that can be used with the `primary` -and `tertiary` options: - -- `$red-palette` -- `$green-palette` -- `$blue-palette` -- `$yellow-palette` -- `$cyan-palette` -- `$magenta-palette` -- `$orange-palette` -- `$chartreuse-palette` -- `$spring-green-palette` -- `$azure-palette` -- `$violet-palette` -- `$rose-palette` - -##### Custom theme -Alternatively, custom palettes can be generated with a custom color with the following schematic: - -```shell -ng generate @angular/material:theme-color ``` - -This schematic integrates with [Material Color Utilities](https://github.com/material-foundation/material-color-utilities) to build palettes based on a single color. Optionally you can provide -additional custom colors for the secondary, tertiary, and neutral palettes. - -The output of the schematic is a new Sass file that exports the palettes that can be provided to -a theme definition. - -```scss @use '@angular/material' as mat; -@use './path/to/my-theme'; // location of generated file html { - @include mat.theme( - color: ( - primary: my-theme.$primary-palette, - tertiary: my-theme.$tertiary-palette, - ), + color-scheme: light dark; + @include mat.theme(( + color: mat.$violet-palette, typography: Roboto, - density: 0, - ) + density: 0 + )); } ``` -You can also optionally generate high contrast override mixins for your custom theme that allows for -a better accessibility experience. Learn more about this schematic in its [documentation](https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/theme-color/README.md). +You can use the following styles to apply the theme’s surface background and +on-surface text colors as a default across your application: - +``` +body { + background: var(--mat-sys-surface); + color: var(--mat-sys-on-surface); +} +``` -#### Customizing your typography +The `mat.theme` mixin will only declare CSS variables for the categories +included in the input. For example, if `typography` is not defined, then +typography CSS variables will not be included in the output. -The following aspects of your app's typography can be customized via the `typography` property of -the theme configuration object. +### **Color** -| Typography Property | Description | -| ------------------- | -------------------------------------------------------------------- | -| `plain-family` | [Optional] The font family to use for plain text, such as body text. | -| `brand-family` | [Optional] The font family to use for brand text, such as headlines. | -| `bold-weight` | [Optional] The font weight to use for bold text. | -| `medium-weight` | [Optional] The font weight to use for medium text. | -| `regular-weight` | [Optional] The font weight to use for regular text. | +The `theme`‘s color determines the component color styles, such as the fill +color of checkboxes or ripple color of buttons. It depends on color palettes of +varying tones to build a color scheme. Check out the +[Palettes](https://docs.google.com/document/d/1tJiP7Z3kQdx94gwK3HKtfP-qioWHAsF3TQW7mbjM7YQ/edit?resourcekey=0-CngmrlEF51YAuYAJQwPBOw&tab=t.0#heading=h.rbsv65h8pako) +section to learn about available prebuilt palettes, or how to create custom +palettes. -See the [typography guide](https://material.angular.io/guide/typography) for more -information. +You can set the color in one of two ways: as a single color palette, or as a +color map. -#### Customizing your density +#### *Single Color Palette* -The following aspects of your app's density can be customized via the `density` property of the -theme configuration object: +If you provide a single color palette, Angular Material uses its values for the +theme’s primary, secondary, and tertiary colors. The CSS color values will be +defined using `light-dark` CSS color function. Your application styles should +define an explicit value declaration for the `color-scheme` CSS property. -| Density Property | Description | -| ---------------- | ---------------------------------------------------------------------------------------------------------------- | -| `scale` | [Optional] The level of compactness of the components in your app, from `0` (most space) to `-5` (most compact). | +#### *Color Map* +If you provide a color map, then the tertiary color palette can be configured +separately from the primary palette. The tertiary palette can be used to add a +distinct accent color to some components. -#### Applying a theme to components +You can also set the `theme-type` to determine the color values are defined: -The `core-theme` Sass mixin emits prerequisite styles for common features used by multiple -components, such as ripples. This mixin must be included once per theme. +* `color-scheme` \- include both light and dark colors using the `light-dark` + CSS color function +* `light` \- only define the light color values +* `dark` \- only define the dark color values -Each Angular Material component has a mixin for each [theming dimension](#theming-dimensions): base, -color, typography, and density. For example, `MatButton` declares `button-base`, `button-color`, -`button-typography`, and `button-density`. Each mixin emits only the styles corresponding to that -dimension of customization. +The `light-dark` CSS color function is +[widely available](https://caniuse.com/?search=light-dark) for all major +browsers. However, if your application must support older browser versions or +non-major browsers, you should explicitly set the `theme-type` to either `light` +or `dark`. -Additionally, each component has a "theme" mixin that emits all styles that depend on the theme -config. This theme mixin only emits color, typography, or density styles if you provided a -corresponding configuration to `define-theme`, and it always emits the base styles. +The following example theme file applies a violet primary color and orange +tertiary color. The theme-type is set to `light` which means that only the light +color values will be set for the application. The typography is set to Roboto +with a standard density setting. -Once you've created your theme, you can apply it using the same `-theme`, `-color`, `-typography`, `-density`, and `-base` mixins. +``` +@use '@angular/material' as mat; -For M3 themes, these mixins make some guarantees about the emitted styles. +html { + @include mat.theme(( + color: ( + primary: mat.$violet-palette, + tertiary: mat.$orange-palette, + theme-type: light, + ), + typography: Roboto, + density: 0 + )); +} +``` -- The mixins emit properties under the exact selector you specify. They will _not_ add to the - selector or increase the specificity of the rule. -- The mixins only emit - [CSS custom property declarations](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) - (e.g. `--some-prop: xyz`). They do _not_ emit any standard CSS properties such as `color`, - `width`, etc. +### **Typography** -Apply the styles for each of the components used in your application by including each of their -theme Sass mixins. +The `mat.theme` ‘s typography determines the text styles used in components, +such as the font for dialog titles or menu list items. -```scss -@use '@angular/material' as mat; +You can set the typography in one of two ways: as a single font family value, or +as a typography map. -$my-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$violet-palette, - ), -)); +#### *Single Font Family Value* -html { - // Emit theme-dependent styles for common features used across multiple components. - @include mat.core-theme($my-theme); +If you provide a font family, Angular Material uses it for all the text in its +components. The font weights used in components are set to 700 for bold text, +500 for medium text, and 400 for regular text. - // Emit styles for MatButton based on `$my-theme`. Because the configuration - // passed to `define-theme` omits typography, `button-theme` will not - // emit any typography styles. - @include mat.button-theme($my-theme); +#### *Typography Map* - // Include the theme mixins for other components you use here. -} -``` +If you provide a typography map, then distinct font families are set for plain +and brand text. The plain font family is typically used for most of the +application’s text, while the brand font family is typically used for headings +and titles. -As an alternative to listing every component that your application uses, Angular Material offers -Sass mixins that includes styles for all components in the library: `all-component-bases`, -`all-component-colors`, `all-component-typographies`, `all-component-densities`, and -`all-component-themes`. These mixins behave the same as individual component mixins, except they -emit styles for `core-theme` and _all_ 35+ components in Angular Material. Unless your application -uses every single component, this will produce unnecessary CSS. +The typography map also sets specific weights for bold, medium, and regular +text. -```scss -@use '@angular/material' as mat; +The following example theme file applies the Roboto font family to plain text +and the Open Sans font family to brand text. It specifies that bold weight is +900, medium weight is 500, and regular weight is 300\. The color scheme uses the +violet color palette with a standard density. -$my-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$violet-palette, - ), -)); +``` +@use '@angular/material' as mat; html { - @include mat.all-component-themes($my-theme); + @include mat.theme(( + color: mat.$violet-palette, + typography: ( + plain-family: Roboto + brand-family: Open Sans, + bold-weight: 900, + medium-weight: 500, + regular-weight: 300, + ), + density: 0, + )); } ``` -To include the emitted styles in your application, [add your theme file to the `styles` array of -your project's `angular.json` file][adding-styles]. +### **Density** -[adding-styles]: https://angular.dev/reference/configs/workspace-config#styles-and-scripts-configuration +The `mat.theme` ‘s density value determines the spacing within components, such +as how much padding is used around a button’s text or the height of form fields. -#### Theming dimensions +The density value accepts integers from 0 to \-5, where 0 is the default spacing +and \-5 is the most dense and compact layout. Each whole number step down (-1, +\-2, etc.) reduces the affected sizes by 4px, down to the minimum size necessary +for a component to render itself coherently. -Angular Material themes are divided along four dimensions: base, color, typography, and density. +The following example theme file has a density setting of \-2 which causes most +components to include less whitespace in their layout. The color scheme uses the +violet color palette and applies Roboto as the font-family. -##### Base +``` +@use '@angular/material' as mat; -Common base styles for the design system. These styles don't change based on your configured -colors, typography, or density, so they only need to be included once per application. These -mixins include structural styles such as border-radius, border-width, etc. All components have a base -mixin that can be used to include its base styles. (For example, -`@include mat.checkbox-base($theme)`) +html { + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: -2, + )); +} +``` -##### Color +Setting the density below 0 can reduce accessibility and make navigation harder +for users of assistive technology. -Styles related to the colors in your application. These style should be included at least once in -your application. Depending on your needs, you may need to include these styles multiple times -with different configurations. (For example, if your app supports light and dark theme colors.) -All components have a color mixin that can be used to include its color styles. (For example, -`@include mat.checkbox-color($theme)`) +Density customizations do not affect components that appear in task-based or +pop-up contexts, such as the date picker. The Material Design density guidance +explicitly discourages changes to density for such interactions because they +don't compete for space in the application's layout. -##### Typography +## **Color Palettes** -Styles related to the fonts used in your application, including the font family, size, weight, -line-height, and letter-spacing. These style should be included at least once in your application. -Depending on your needs, you may need to include these styles multiple times with different -configurations. (For example, if your app supports reading content in either a serif or sans-serif -font.) All components have a typography mixin that can be used to include its typography -styles. (For example, `@include mat.checkbox-typography($theme)`) +A color palette is a set of similar colors with different hues ranging from +light to dark. The Angular Material theme uses color palettes to create a color +scheme to communicate an application’s hierarchy, state, and brand. -##### Density +### **Prebuilt Color Palettes** -Styles related to the size and spacing of elements in your application. These style should be -included at least once in your application. Depending on your needs, you may need to include these -styles multiple times with different configurations. (For example, if your app supports both a -normal and compact mode). All components have a density mixin that can be used to include its -density styles. (For example, `@include mat.checkbox-density($theme)`) +Angular Material provides twelve prebuilt color palettes that can be used for +your application’s theme: -##### Theme mixin +* `$red-palette` +* `$green-palette` +* `$blue-palette` +* `$yellow-palette` +* `$cyan-palette` +* `$magenta-palette` +* `$orange-palette` +* `$chartreuse-palette` +* `$spring-green-palette` +* `$azure-palette` +* `$violet-palette` +* `$rose-palette` -All components also support a theme mixin that can be used to include the component's styles for all -theme dimensions at once. (For example, `@include mat.checkbox-theme($theme)`). +### **Custom Color Palettes** -**The recommended approach is to rely on the `theme` mixins to lay down your base styles, and if -needed use the single dimension mixins to override particular aspects for parts of your app (see the -section on [Multiple themes in one file](#multiple-themes-in-one-file).)** +The Angular Material +[palette generation schematic](https://github.com/angular/components/blob/main/src/material/schematics/ng-generate/m3-theme/README.md) +builds custom color palettes based on a single color input for the primary +color, and optionally color inputs to further customize secondary, tertiary, and +neutral palettes: -### Defining multiple themes +``` +ng generate @angular/material:theme +``` -Using the Sass API described in [Defining a theme](#defining-a-theme), you can also define -_multiple_ themes by repeating the API calls multiple times. You can do this either in the same -theme file or in separate theme files. +## **Loading Fonts** -#### Multiple themes in one file +You can use Google Fonts as one option to load fonts in your application. For +example, the following code in an application’s `` loads the font family +Roboto with the font weights 700, 500, and 400: -Defining multiple themes in a single file allows you to support multiple themes without having to -manage loading of multiple CSS assets. The downside, however, is that your CSS will include more -styles than necessary. +``` + + + +``` -To control which theme applies when, `@include` the mixins only within a context specified via -CSS rule declaration. See the [documentation for Sass mixins][sass-mixins] for further background. +Learn more about using fonts with +[Google Fonts](https://developers.google.com/fonts/docs/getting_started). By +default, projects created with the Angular CLI are +[configured](https://angular.dev/reference/configs/workspace-config#fonts-optimization-options) +to inline assets from Google Fonts to reduce render-blocking requests. -[sass-mixins]: https://sass-lang.com/documentation/at-rules/mixin +## **Supporting Light and Dark Mode** -```scss -@use '@angular/material' as mat; +By default, the `mat.theme` mixin defines colors using the CSS color function +`light-dark` to make it easy for your application to switch between light and +dark mode. The `light-dark` function depends on the value of `color-scheme` +declared in your application’s global styles. If your application does not +define a value for `color-scheme`, then the light colors will always be applied. -// Define a dark theme -$dark-theme: mat.define-theme(( - color: ( - theme-type: dark, - primary: mat.$violet-palette, - ), -)); - -// Define a light theme -$light-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$violet-palette, - ), -)); +You can define `color-scheme: light` or `color-scheme: dark` to explicitly +define your application’s mode. To set the mode depending on the user’s system +preferences, use `color-scheme: light-dark` as shown in the following example: + +``` +@use '@angular/material' as mat; html { - // Apply the dark theme by default - @include mat.core-theme($dark-theme); - @include mat.button-theme($dark-theme); - - // Apply the light theme only when the user prefers light themes. - @media (prefers-color-scheme: light) { - // Use the `-color` mixins to only apply color styles without reapplying the same - // typography and density styles. - @include mat.core-color($light-theme); - @include mat.button-color($light-theme); - } + color-scheme: light dark; + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: 0 + )); } ``` -#### Multiple themes across separate files - -You can define multiple themes in separate files by creating multiple theme files per -[Defining a theme](#defining-a-theme), adding each of the files to the `styles` of your -`angular.json`. However, you must additionally set the `inject` option for each of these files to -`false` in order to prevent all the theme files from being loaded at the same time. When setting -this property to `false`, your application becomes responsible for manually loading the desired -file. The approach for this loading depends on your application. - -### Application background color - -By default, Angular Material does not apply any styles to your DOM outside -its own components. If you want to set your application's background color -to match the components' theme, you can either: -1. Put your application's main content inside `mat-sidenav-container`, assuming you're using - `MatSidenav`, or -2. Apply the `mat-app-background` CSS class to your main content root element (typically `body`). - -### Granular customizations with CSS custom properties - -The CSS custom properties emitted by the theme mixins are derived from -[M3's design tokens](https://m3.material.io/foundations/design-tokens/overview). To further -customize your UI beyond the `define-theme` API, you can manually set these custom properties in -your styles. - -The guarantees made by the theme mixins mean that you do not need to target internal selectors of -components or use excessive specificity to override any of these tokenized properties. Always apply -your base theme to your application's root element (typically `html` or `body`) and apply any -overrides on the highest-level selector where they apply. - - - -```html - - Some content... - - Some sidenav content... - Enable admin mode - - -``` +You can also use the strategy of defining `color-scheme` under a CSS selector so +that the mode depends on whether that class has been applied. In the following +example, the application always displays the light mode theme unless the class +“dark-mode” is added to the HTML body. -```scss +``` @use '@angular/material' as mat; -$light-theme: mat.define-theme(); -$dark-theme: mat.define-theme(( - color: ( - theme-type: dark - ) -)); - html { - // Apply the base theme at the root, so it will be inherited by the whole app. - @include mat.all-component-themes($light-theme); -} - -mat-sidenav { - // Override the colors to create a dark sidenav. - @include mat.all-component-colors($dark-theme); -} - -.danger { - // Override the checkbox hover state to indicate that this is a dangerous setting. No need to - // target the internal selectors for the elements that use these variables. - --mdc-checkbox-unselected-hover-state-layer-color: red; - --mdc-checkbox-unselected-hover-icon-color: red; + color-scheme: light; + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: 0 + )); } -``` -## Customizing density - -Angular Material's density customization is based on the -[Material Design density guidelines][material-density]. This system defines a scale where zero -represents the default density. You can decrement the number for _more density_ and increment the -number for _less density_. - -The density system is based on a *density scale*. The scale starts with the -default density of `0`. Each whole number step down (`-1`, `-2`, etc.) reduces -the affected sizes by `4dp`, down to the minimum size necessary for a component to render -coherently. - -Components that appear in task-based or pop-up contexts, such as `MatDatepicker`, don't change their -size via the density system. The [Material Design density guidance][material-density] explicitly -discourages increasing density for such interactions because they don't compete for space in the -application's layout. - -You can apply custom density setting to the entire library or to individual components using their -density Sass mixins. - -```scss -// You can set a density setting in your theme to apply to all components. -$dark-theme: mat.define-theme(( - color: ..., - typography: ..., - density: ( - scale: -2 - ), -)); - -// Or you can selectively apply the Sass mixin to affect only specific parts of your application. -.the-dense-zone { - @include mat.button-density(-1); +body.dark-mode { + color-scheme: dark; } ``` -[material-density]: https://m3.material.io/foundations/layout/understanding-layout/spacing +Angular Material does not automatically apply different styles or themes based +on user preference media queries, such as `color-scheme`, `prefers-color-scheme` +or `prefers-contrast`. Instead, Angular Material gives you the flexibility to +define your own queries to apply the styles that make sense for your users. This +may mean relying on `color-scheme: light dark`, defining custom media queries, +or reading a saved user preference to apply styles. -## Strong focus indicators +## **Multiple Themes** -By default, most components indicate browser focus by changing their background color as described -by the Material Design specification. This behavior, however, can fall short of accessibility -requirements, such as [WCAG][], which require a stronger indication of browser focus. +You can call the `mat.theme` mixin more than once to apply multiple different +color schemes in your application. -Angular Material supports rendering highly visible outlines on focused elements. Applications can -enable these strong focus indicators via two Sass mixins: -`strong-focus-indicators` and `strong-focus-indicators-theme`. +### **Context-specific Themes** -The `strong-focus-indicators` mixin emits structural indicator styles for all components. This mixin -should be included exactly once in an application, similar to the `core` mixin described above. +The following example theme file customizes the theme for components in +different contexts. In this case, a cyan-based palette is applied to a container +of information about deleting data, causing buttons and other components to have +a unique and attention-grabbing style applied: -The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should -be included once per theme, similar to the theme mixins described above. Additionally, you can use -this mixin to change the color of the focus indicators in situations in which the default color -would not contrast sufficiently with the background color. - -The following example includes strong focus indicator styles in an application alongside the rest of -the custom theme API. - -```scss +``` @use '@angular/material' as mat; -@include mat.strong-focus-indicators(); - -$my-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$violet-palette, - ), -)); - html { - @include mat.all-component-themes($my-theme); - @include mat.strong-focus-indicators-theme($my-theme); + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: 0, + )); } -``` - -### Customizing strong focus indicators -You can pass a configuration map to `strong-focus-indicators` to customize the appearance of the -indicators. This configuration includes `border-style`, `border-width`, and `border-radius`. +.example-bright-container { + @include mat.theme(( + color: mat.$cyan-palette, + )); +} +``` -You also can customize the color of indicators with `strong-focus-indicators-theme`. This mixin -accepts either a theme, as described earlier in this guide, or a CSS color value. When providing a -theme, the indicators will use the default hue of the primary palette. +## **Using Theme Styles** -The following example includes strong focus indicator styles with custom settings alongside the rest -of the custom theme API. +An application’s custom components can use the CSS variables defined by +`mat.theme` to apply the theme’s colors and typography. -```scss -@use '@angular/material' as mat; +The color variables are useful for emphasizing important text and actions, +providing stronger application branding, and ensuring strong contrast ratios +between surface and on-surface elements. -@include mat.strong-focus-indicators(( - border-style: dotted, - border-width: 4px, - border-radius: 2px, -)); +The typography variables are useful for creating clear information hierarchy and +text consistency through the application. -$my-theme: mat.define-theme(( - color: ( - theme-type: light, - primary: mat.$violet-palette, - ), -)); +The following example styles demonstrate a component using the color and +typography variables to create an application-wide banner presenting important +information to the user: -html { - @include mat.all-component-themes($my-theme); - @include mat.strong-focus-indicators-theme(purple); +``` +:host { + background: var(--mat-sys-primary-container); + color: var(--mat-sys-on-primary-container); + border: 1px solid var(--mat-sys-outline-variant); + font: var(--mat-sys-body-large); } ``` -[WCAG]: https://www.w3.org/WAI/standards-guidelines/wcag/glance/ +See the [Theme Variables](https://ng-comp-devapp.web.app/theme) guide for a +comprehensive list of these variables, examples of where they are used, and how +components can depend on them. -## Theming and style encapsulation +## **Customizing Tokens** -Angular Material assumes that, by default, all theme styles are loaded as global CSS. If you want -to use [Shadow DOM][shadow-dom] in your application, you must load the theme styles within each -shadow root that contains an Angular Material component. You can accomplish this by manually loading -the CSS in each shadow root, or by using [Constructable Stylesheets][constructable-css]. +Angular Material components also allow for narrowly targeted customization of +specific tokens through the `overrides` mixins. This enables fine-grained +adjustments to specific system-level theme CSS variables as well as individual +component tokens, such as a component’s border-color or title font size. -[shadow-dom]: https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM -[constructable-css]: https://developers.google.com/web/updates/2019/02/constructable-stylesheets +The `overrides` API validates that the customized tokens are correctly spelled +and can be used to ensure backwards compatibility if tokens are added, moved, or +renamed in future versions. -## User preference media queries +### **System Tokens** -Angular Material does not apply styles based on user preference media queries, such as -`prefers-color-scheme` or `prefers-contrast`. Instead, Angular Material's Sass mixins give you the -flexibility to apply theme styles to based on the conditions that make the most sense for your -users. This may mean using media queries directly or reading a saved user preference. +System-level tokens can be changed to different values through the +`mat.theme-overrides` mixin, which will redefine CSS variables that are used in +the application. -## Using component color variants +The following example applies a violet color palette for the application, but +alters the `primary-container` token to a specific shade of blue. -A number of components have a `color` input property that allows developers to apply different color -variants of the component. When using an M3 theme, this input still adds a CSS class to the -component (e.g. `.mat-accent`). However, there are no built-in styles targeting these classes. You -can instead apply color variants by passing the `$color-variant` option to a component's `-theme` or -`-color` mixins. +``` +@use '@angular/material' as mat; - +html { + color-scheme: light dark; + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: 0 + )); -```html - -
- -
+ .example-orange-primary-container { + @include mat.theme-overrides(( + primary-container: #84ffff + )); + } +} ``` -```scss -@use '@angular/material' as mat; +Alternatively, an optional override map can be provided in the `mat.theme` mixin +to replace values applied by the mixin: -$theme: mat.define-theme(); +``` +@use '@angular/material' as mat; -.tertiary-checkbox { - @include mat.checkbox-color($theme, $color-variant: tertiary); +html { + color-scheme: light dark; + @include mat.theme(( + color: mat.$violet-palette, + typography: Roboto, + density: 0 + ), $overrides: ( + primary-container: orange, + ); } ``` -This API is more flexible, and produces less CSS. For example, the `.tertiary-checkbox` class shown -above can be applied to any checkbox _or_ any element that contains checkboxes, to change the color -of all checkboxes within that element. - -While you should prefer applying the mixins with color variants explicitly, if migrating from M2 to -M3 you can alternatively use [the provided backwards compatibility mixins](https://material.angular.io/guide/material-2-theming#how-to-migrate-an-app-from-material-2-to-material-3) -that apply styles directly to the existing CSS classes (`mat-primary`, `mat-accent`, and -`mat-warn`). - -The table below shows the supported `$color-variant` values for each component. (Unlisted components -do not support any color variants.) - -| Component | Supported `$color-variant` values | Default | -| ---------------- | ------------------------------------------------------ | ----------- | -| Badge | `primary`, `secondary`, `tertiary`, `error` | `error` | -| Button | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Button-toggle | `primary`, `secondary`, `tertiary`, `error` | `secondary` | -| Checkbox | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Chips | `primary`, `secondary`, `tertiary`, `error` | `secondary` | -| Datepicker | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Fab | `primary`, `secondary`, `tertiary` | `primary` | -| Form-field | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Icon | `surface`, `primary`, `secondary`, `tertiary`, `error` | `surface` | -| Option | `primary`, `secondary`, `tertiary`, `error` | `secondary` | -| Progress-bar | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Progress-spinner | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Pseudo-checkbox | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Radio | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Select | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Slide-toggle | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Slider | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Stepper | `primary`, `secondary`, `tertiary`, `error` | `primary` | -| Tabs | `primary`, `secondary`, `tertiary`, `error` | `primary` | - -## Style customization outside the theming system - -Angular Material supports customizing color, typography, and density as outlined in this document. -Angular strongly discourages, and does not directly support, overriding component CSS outside the -theming APIs described above. Component DOM structure and CSS classes are considered private -implementation details that may change at any time. - - -## Theme your own components using a Material 3 theme - -The same utility functions for reading properties of M2 themes (described in -[our guide for theming your components](https://material.angular.io/guide/theming-your-components)) -can be used to read properties from M3 themes. However, the named palettes, typography -levels, etc. available are different for M3 themes, in accordance with the spec. - -The structure of the theme object is considered an implementation detail. Code should not depend on -directly reading properties off of it, e.g. using `map.get`. Always use the utility functions -provided by Angular Material to access properties of the theme. - - - -```scss -@use '@angular/material' as mat; +### **Component Tokens** -@mixin my-comp-theme($theme) { - .my-comp { - font: mat.get-theme-typography($theme, body-large, font); - letter-spacing: mat.get-theme-typography($theme, body-large, letter-spacing); - background: mat.get-theme-color($theme, surface); - @if mat.get-theme-type($theme) == dark { - color: mat.get-theme-color($theme, primary, 20); - } @else { - color: mat.get-theme-color($theme, primary, 80); - } - padding: 48px + (2px * mat.get-theme-density($theme)); - } +Each Angular Material component defines an `overrides` mixin that can be used to +customize tokenized styles for their color, typography, and density. + +More information for each component’s override API, including their list of +available customizable tokens, can be found on their respective documentation +page under the Styling tab. + +The following example demonstrates the Card’s `overrides` API to change the +background color to red, increase the corner border radius, and specify a larger +title font size. + +``` +html { + @include mat.card-overrides(( + elevated-container-color: red, + elevated-container-shape: 32px, + title-text-size: 2rem, + )); } ``` + +### **Direct Style Overrides** + +Angular Material supports customizing color, typography, and density as outlined +in this document. Angular strongly discourages, and does not directly support, +overriding component CSS outside the theming APIs described above. Component DOM +structure and CSS classes are considered private implementation details that may +change at any time. CSS variables used by the Angular Material components should +be defined through the `overrides` API instead of defined explicitly. + +## **Shadow DOM** + +Angular Material assumes that, by default, all theme styles are loaded as global +CSS. If you want to use +[Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) +in your application, you must load the theme styles within each shadow root that +contains an Angular Material component. You can accomplish this by manually +loading the CSS in each shadow root, or by using +[Constructable Stylesheets](https://developers.google.com/web/updates/2019/02/constructable-stylesheets). diff --git a/guides/typography.md b/guides/typography.md deleted file mode 100644 index 9f39aeaa4f8d..000000000000 --- a/guides/typography.md +++ /dev/null @@ -1,146 +0,0 @@ -# Customizing Typography - -**Note: The information on this page is specific to Material 3, for Material 2 -information on typography go to the [Material 2 guide](https://material.angular.io/guide/material-2-theming#customizing-typography).** - -## What is typography? - -Typography is a way of arranging type to make text legible, readable, and appealing when displayed. -Angular Material's [theming system][theming-system] supports customizing the typography settings -for the library's components. Additionally, Angular Material provides APIs for applying typography -styles to elements in your own application. - -Angular Material's theming APIs are built with [Sass](https://sass-lang.com). This document assumes -familiarity with CSS and Sass basics, including variables, functions, and mixins. - -[theming-system]: https://material.angular.io/guide/theming - -## Including font assets - -Angular Material's typography APIs lets you specify any font-face. The default font-face value is -configured to [Google's Roboto font][roboto] with the 300, 400, and 500 font-weight styles. To use -Roboto, your application must load the font, which is not included with Angular Material. The -easiest way to load Roboto, or any other custom font, is by using Google Fonts. The following -snippet can be placed in your application's `` to load Roboto from Google Fonts. - -```html - - -``` - -See [Getting Started with the Google Fonts API][fonts-api] for more about using Google Fonts. Also -note that, by default, [the Angular CLI inlines assets from Google Fonts to reduce render-blocking -requests][font-inlining]. - -[roboto]: https://fonts.google.com/share?selection.family=Roboto:wght@300;400;500 -[fonts-api]: https://developers.google.com/fonts/docs/getting_started -[font-inlining]: https://angular.dev/reference/configs/workspace-config#fonts-optimization-options - -## Configuring Typography - -The following aspects of your app's typography can be customized via the `typography` property of -the theme configuration object. - -| Typography Property | Description | -| ------------------- | -------------------------------------------------------------------- | -| `plain-family` | [Optional] The font family to use for plain text, such as body text. | -| `brand-family` | [Optional] The font family to use for brand text, such as headlines. | -| `bold-weight` | [Optional] The font weight to use for bold text. | -| `medium-weight` | [Optional] The font weight to use for medium text. | -| `regular-weight` | [Optional] The font weight to use for regular text. | - -These are used to generate the styles for the different typescale levels. - -## Type scale levels - -A **type scale** is a selection of font styles that can be used across an app. -They’re assigned based on use (such as display or headline), and grouped more -broadly into categories based on scale (such as large or small). For more -information, see the [M3 typography spec](https://m3.material.io/styles/typography/type-scale-tokens). - -There are `large`, `medium`, and `small` variations for the following type roles: -- **Display**: Display styles are reserved for short, important text or numerals. They work best on large screens. -- **Headline**: Headline styles are best-suited for short, high-emphasis text on smaller screens. These styles can be good for marking primary passages of text or important regions of content. -- **Title**: Title styles are smaller than headline styles, and should be used for medium-emphasis text that remains relatively short. For example, consider using title styles to divide secondary passages of text or secondary regions of content. -- **Body**: Body styles are used for longer passages of text in your app. -- **Label**: Label styles are smaller, utilitarian styles, used for things like the text inside components or for very small text in the content body, such as captions. - -The table below lists the CSS classes emitted and the native elements styled. - -| CSS class | Typesale level | -|---------------------------|---------------------| -| `.mat-display-large` | `display-large` | -| `.mat-display-medium` | `display-medium` | -| `.mat-display-small` | `display-small` | -| `.mat-headline-large` | `headline-large` | -| `.mat-headline-medium` | `headline-medium` | -| `.mat-headline-small` | `headline-small` | -| `.mat-title-large` | `title-large` | -| `.mat-title-medium` | `title-medium` | -| `.mat-title-small` | `title-small` | -| `.mat-body-large` | `body-large` | -| `.mat-body-medium` | `body-medium` | -| `.mat-body-small` | `body-small` | -| `.mat-label-large` | `label-large` | -| `.mat-label-medium` | `label-medium` | -| `.mat-label-small` | `label-small` | - -## Using typography styles in your application - -See the [theming guide](https://material.angular.io/guide/theming#defining-a-theme) -for details on setting up a theme that has typography configured. - -### Reading typography values from a config - -It is possible to read typography properties from a theme for use in your own components. For more -information about this see our guide on [Theming your own components][reading-typography]. - -[reading-typography]: https://material.angular.io/guide/theming-your-components#reading-typography-values - -## Using typography styles in your application - -**Note: this section is applicable only if you are using the [M2 backwards compatability -mixin](https://material.angular.io/guide/material-2-theming#optional-add-backwards-compatibility-styles-for-typography-hierarchy).** - -In addition to styles shared between components, the `typography-hierarchy` mixin includes CSS -classes for styling your application. These CSS classes correspond to the typography levels in your -typography config. This mixin also emits styles for native header elements scoped within the -`.mat-typography` CSS class. - -```scss -@use '@angular/material' as mat; - -// Use the default configuration. -$my-typography: mat.define-typography-config(); -@include mat.typography-hierarchy($my-typography); -``` - -In addition to the typographic styles, these style rules also include a `margin-bottom` for -headers and paragraphs. For `body` styles, text is styled within the provided CSS selector. - -The `.mat-h5` and `.mat-h6` styles don't directly correspond to a specific Material Design -typography level. The `.mat-h5` style uses the `body-2` level with the font-size scaled down by -`0.83`. The `.mat-h6` style uses the `body-2` level with the font-size scaled down by `0.67`. - -The `button` typography level does not map to a CSS class. - -The following example demonstrates usage of the typography styles emitted by the -`typography-hierarchy` mixin. - -```html - - -

Top header

- - -

Introductory text

- -
- -

Inner header

- - -

Some inner text

-
- -```