- Angular Material components depend on system variables defined as CSS variables through the - material.theme - Sass mixin. This page provides guidance and documentation for using these variables to - customize components. -
- -- Material Design uses color to create accessible, personal color schemes - that communicate your product's hierarchy, state, and brand. See Material - Design's Color System - page to learn more about its use and purpose. -
-- The following colors are the most often used in Angular Material components. Use these - colors and follow their uses to add theme colors to your application's custom components. -
- -- The most common color used by Angular Material components to - participate in the application theme. -
-- Examples include the background color - of filled buttons, the icon color of selected radio buttons, and the - outline color of form fields. -
-- Use the color --mat-sys-on-primary for - icons, text, and other visual elements placed on a primary background. This - color is calculated to be optimal for accessibility and legibility. -
-- A low-emphasis background color that provides a clear contrast for - both light and dark themes and their varied theme colors. -
-- Examples include the background color of the application and most - components such as the dialog, card, table, and more. -
-- Use the color --mat-sys-on-surface for - icons, text, and other visual elements placed on a surface background. This - color is calculated to be optimal for accessibility and legibility. -
-- High-contrast color meant to alert the user to attract immediate attention. -
-- Examples include the background color of the badge and the text color of invalid - form fields inputs. -
-- Use the color --mat-sys-on-error for - icons, text, and other visual elements placed on an error background. This - color is calculated to be optimal for accessibility and legibility. -
-- Used for borders and dividers to help provide visual separation between - and around elements. -
-- Examples include the color of the divider and border color of an outlined - form field. -
-- Use the color --mat-sys-outline-variant for a less - prominent outline. -
-- These colors are less commonly used in Angular Material components but - are available for adding color variety and creating additional emphasis - to components. -
-- Colors may be paired with a --mat-sys-on- variable - that should be used for text and icons placed within a filled container. -
- -- The following colors should be used for backgrounds and large, - low-emphasis areas of the screen. -
- -- Containers filled with a surface color should apply the - --mat-sys-on-surface color to text - and icons placed within. -
- -- These colors are the same for both light and dark themes. They are unused - by any Angular Material components. -
- -- There are five categories of font types defined by Material Design: body, display, headline, - label, and title. Each category has three sizes: small, medium, and large. -
-- Learn more about how these categories and their sizes should be used in your application by - visiting Material Design's - Typography documentation. -
- - -@for (category of ['body', 'display', 'headline', 'label', 'title']; track $index) { -- Each system variable can be applied to the "font" CSS style. Additionally, the parts of the variable definition - can be accessed individually by appending the keywords "font", "line-height", "size", "tracking", and "weight". -
-- For example, the values for medium body text may be defined as follows: -
----mat-sys-body-medium: 400 0.875rem / 1.25rem Roboto, sans-serif; ---mat-sys-body-medium-font: Roboto, sans-serif; ---mat-sys-body-medium-line-height: 1.25rem; ---mat-sys-body-medium-size: 0.875rem; ---mat-sys-body-medium-tracking: 0.016rem; ---mat-sys-body-medium-weight: 400; -- -
- Material Design provides six levels of elevation that can be used to provide - a sense of depth and organization to an application's UI. Learn more at Material Design's - Elevation guide. -
- -- These levels are defined as CSS box-shadow values that can be styled to an element. -
- -@for (level of [0, 1, 2, 3, 4, 5]; track $index) { -- The mat.theme-overrides mixin - can be included to emit different definitions for the system variables and - override the definitions emitted from mat.theme. -
- -- @include mat.theme-overrides(( - primary: #ebdcff, - on-primary: #230f46, - body-medium: 500 1.15rem/1.3rem Arial, - corner-large: 32px, - level3: 0 4px 6px 1px var(--mat-sys-surface-dim), - ));-
+.mat-bg-primary {
+ background-color: var(--mat-sys-primary);
+}
+
+
+A primary container color background is useful for filling components that should stand out on a
+surface. In Angular Material, this is used for the container of a floating action button.
+
+
+.mat-bg-primary-container {
+ background-color: var(--mat-sys-primary-container);
+}
+
+
+
+.mat-bg-secondary {
+ background-color: var(--mat-sys-secondary);
+}
+
+
+A secondary container color background is useful for components that need less emphasis than
+secondary, such as filter chips. In Angular Material, this is used for selected items in a list and
+the container of a tonal button.
+
+
+.mat-bg-secondary-container {
+ background-color: var(--mat-sys-secondary-container);
+}
+
+
+
+.mat-bg-error {
+ background-color: var(--mat-sys-error);
+}
+
+
+An error container color background is useful for components that need less emphasis than error,
+such as a container for error text.
+
+
+.mat-bg-error-container {
+ background-color: var(--mat-sys-error-container);
+}
+
+
+
+.mat-bg-surface {
+ background-color: var(--mat-sys-surface);
+}
+
+
+A surface variant background is useful for surfaces that need to stand out from the main surface
+color. In Angular Material, this is used for the background of a filled form field and the track of
+a progress bar.
+
+
+.mat-bg-surface-variant {
+ background-color: var(--mat-sys-surface-variant);
+}
+
+
+The "highest" surface container background is useful for surfaces that need the most emphasis
+against the main surface color. In Angular Material, this is used for the background of a filled
+card.
+
+
+.mat-bg-surface-container-highest {
+ background-color: var(--mat-sys-surface-container-highest);
+}
+
+
+A "high" surface container background is useful for surfaces that need more emphasis against the
+main surface color. In Angular Material, this is used for the background of a datepicker.
+
+
+.mat-bg-surface-container-high {
+ background-color: var(--mat-sys-surface-container-high);
+}
+
+
+A surface container background is useful for surfaces that need to stand out from the main surface
+color. In Angular Material, this is used for the background of a menu.
+
+
+.mat-bg-surface-container {
+ background-color: var(--mat-sys-surface-container);
+}
+
+
+A "low" surface container background is useful for surfaces that need less emphasis against the main
+surface color. In Angular Material, this is used for the background of a bottom sheet.
+
+
+.mat-bg-surface-container-low {
+ background-color: var(--mat-sys-surface-container-low);
+}
+
+
+The "lowest" surface container background is useful for surfaces that need the least emphasis
+against the main surface color.
+
+
+.mat-bg-surface-container-lowest {
+ background-color: var(--mat-sys-surface-container-lowest);
+}
+
+
+An inverse surface color background is useful for making elements stand out against the default
+color scheme. It is good for temporary notifications that appear above your content. In Angular
+Material, this is used for the background of a snackbar and a tooltip.
+
+When using the inverse surface background, text and icons should use the `inverse-on-surface` system
+color token ensure good contrast and accessibility (see [Text](#text) below).
+
+
+.mat-bg-inverse-surface {
+ background-color: var(--mat-sys-inverse-surface);
+}
+
+
+
+.mat-bg-disabled {
+ background-color: color-mix(in srgb, var(--mat-sys-on-surface) 12%, transparent);
+}
+
+
+### Text
+
+
+.mat-text-primary {
+ color: var(--mat-sys-primary);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-secondary {
+ color: var(--mat-sys-secondary);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-error {
+ color: var(--mat-sys-error);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-disabled {
+ color: color-mix(in srgb, var(--mat-sys-on-surface) 38%, transparent);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-surface-variant {
+ color: var(--mat-sys-on-surface-variant);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-primary {
+ color: var(--mat-sys-on-primary);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-primary-container {
+ color: var(--mat-sys-on-primary-container);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-secondary {
+ color: var(--mat-sys-on-secondary);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-secondary-container {
+ color: var(--mat-sys-on-secondary-container);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-error {
+ color: var(--mat-sys-on-error);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-error-container {
+ color: var(--mat-sys-on-error-container);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-on-surface {
+ color: var(--mat-sys-on-surface);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-text-inverse-on-surface {
+ color: var(--mat-sys-inverse-on-surface);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +## Typography + +Material Design provides five categories of font types: body, display, headline, label, and title. +Each category has three sizes: small, medium, and large. Learn more about how these categories and +their sizes should be used in your application by visiting Material +Design's [Applying Type](https://m3.material.io/styles/typography/applying-type) documentation. + +
+.mat-font-body-sm {
+ font: var(--mat-sys-body-small);
+ letter-spacing: var(--mat-sys-body-small-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The medium body typeface is the default body font. In Angular Material, this is used for the text in +a table row and the supporting text in a dialog. + +
+.mat-font-body-md {
+ font: var(--mat-sys-body-medium);
+ letter-spacing: var(--mat-sys-body-medium-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The large body typeface is useful for an introductory paragraph. In Angular Material, this is used +for the text in a list item and the text in a select trigger. + +
+.mat-font-body-lg {
+ font: var(--mat-sys-body-large);
+ letter-spacing: var(--mat-sys-body-large-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-font-display-sm {
+ font: var(--mat-sys-display-small);
+ letter-spacing: var(--mat-sys-display-small-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The medium display typeface is useful for short, impactful text in hero sections or titles on larger +screens. + +
+.mat-font-display-md {
+ font: var(--mat-sys-display-medium);
+ letter-spacing: var(--mat-sys-display-medium-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The large display typeface is useful for short, high-emphasis text in hero sections or titles on +larger screens, providing the most visual weight. + +
+.mat-font-display-lg {
+ font: var(--mat-sys-display-large);
+ letter-spacing: var(--mat-sys-display-large-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-font-headline-sm {
+ font: var(--mat-sys-headline-small);
+ letter-spacing: var(--mat-sys-headline-small-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The medium headline typeface is useful for a section title. + +
+.mat-font-headline-md {
+ font: var(--mat-sys-headline-medium);
+ letter-spacing: var(--mat-sys-headline-medium-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The large headline typeface is useful for a page title on a large screen. + +
+.mat-font-headline-lg {
+ font: var(--mat-sys-headline-large);
+ letter-spacing: var(--mat-sys-headline-large-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-font-label-sm {
+ font: var(--mat-sys-label-small);
+ letter-spacing: var(--mat-sys-label-small-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The medium label typeface is useful for the slider label. + +
+.mat-font-label-md {
+ font: var(--mat-sys-label-medium);
+ letter-spacing: var(--mat-sys-label-medium-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The large label typeface is useful for buttons, chips, and menu labels. + +
+.mat-font-label-lg {
+ font: var(--mat-sys-label-large);
+ letter-spacing: var(--mat-sys-label-large-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +
+.mat-font-title-sm {
+ font: var(--mat-sys-title-small);
+ letter-spacing: var(--mat-sys-title-small-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The medium title typeface is useful for a dialog title or the primary text in a list item. In +Angular Material, this is used for the subtitle of a card and the header of an expansion panel. + +
+.mat-font-title-md {
+ font: var(--mat-sys-title-medium);
+ letter-spacing: var(--mat-sys-title-medium-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +The large title typeface is useful for a page title on a small screen. In Angular Material, this is +used for the title of a card and the title of a toolbar. + +
+.mat-font-title-lg {
+ font: var(--mat-sys-title-large);
+ letter-spacing: var(--mat-sys-title-large-tracking);
+}
+
+
+Example text: Lorem ipsum dolor sit amet, consectetur adipiscing elit.+ +## Shape + +Material Design uses border radius to help direct attention, identify components, communicate state, +and express brand. See Material +Design's [Corner Radius Scale](https://m3.material.io/styles/shape/corner-radius-scale) +documentation to learn more. + +In Angular Material, shape is scoped to varying levels of border-radius. The following code blocks +demonstate the levels of roundness. Their border sizes are increased to 2px to clearly show the +border radii. + +The extra small border radius is useful for components that need a small amount of rounding, such as +a chip. In Angular Material, this is used for the shape of a snackbar and a tooltip. + +
+.mat-corner-xs {
+ border-radius: var(--mat-sys-corner-extra-small);
+}
+
+The small border radius is useful for components that need a small amount of rounding, such as a
+text field.
+
+
+.mat-corner-sm {
+ border-radius: var(--mat-sys-corner-small);
+}
+
+The medium border radius is useful for components that need a medium amount of rounding, such as a
+button. In Angular Material, this is used for the shape of a card.
+
+
+.mat-corner-md {
+ border-radius: var(--mat-sys-corner-medium);
+}
+
+The large border radius is useful for components that need a large amount of rounding, such as a
+card. In Angular Material, this is used for the shape of a floating action button and a datepicker.
+
+
+.mat-corner-lg {
+ border-radius: var(--mat-sys-corner-large);
+}
+
+The extra large border radius is useful for components that need a large amount of rounding. In
+Angular Material, this is used for the shape of a button toggle and the shape of a dialog.
+
+
+.mat-corner-xl {
+ border-radius: var(--mat-sys-corner-extra-large);
+}
+
+The full border radius is useful for components that are circular, such as a user avatar. In Angular
+Material, this is used for the shape of a badge and the shape of a button.
+
+
+.mat-corner-full {
+ border-radius: var(--mat-sys-corner-full);
+}
+
+
+## Elevation
+
+Material Design uses borders and shadows to create a sense of depth and hierarchy in the UI. See
+Material Design's [Applying Elevation](https://m3.material.io/styles/elevation/applying-elevation)
+documentation to
+learn more.
+
+
+.mat-border {
+ border: 1px solid var(--mat-sys-outline);
+}
+
+
+The subtle outline variant is useful for components that need a less obvious boundary. In Angular
+Material, this is used for the outline of an outlined card and the color of the divider.
+
+
+.mat-border-subtle {
+ border: 1px solid var(--mat-sys-outline-variant);
+}
+
+
+
+.mat-shadow-1 {
+ box-shadow: var(--mat-sys-level1);
+}
+
+
+Level 2 elevation can be used to raise the appearance of a surface. In Angular Material, this is
+used for the elevation of a menu and a select panel.
+
+
+.mat-shadow-2 {
+ box-shadow: var(--mat-sys-level2);
+}
+
+
+Level 3 elevation is used to raise the appearance of a surface. In Angular Material, this is used
+for the elevation of a floating action button.
+
+
+.mat-shadow-3 {
+ box-shadow: var(--mat-sys-level3);
+}
+
+
+Level 4 elevation is generally reserved for elevation changes due to interaction like focus and
+hover. In Angular Material, this is used for the elevation of a hovered floating action button.
+
+
+.mat-shadow-4 {
+ box-shadow: var(--mat-sys-level4);
+}
+
+
+Level 5 elevation is used to greatly raise the appearance of a surface and is generally reserved for
+elevation changes due to interaction like focus and hover.
+
+
+.mat-shadow-5 {
+ box-shadow: var(--mat-sys-level5);
+}
+
+
+## Material Design 2 Support
+
+This guide is compatible for applications defining their theme with the "m2" Sass APIs using
+the legacy theme-config approach. To take advantage of CSS variables and the utility classes,
+you can call `@include mat.m2-theme($theme)` in your theme file, which will define
+system tokens according to the Material Design 2 system that matches your current theme
+configuration.
+
+```scss
+@use '@angular/material' as mat;
+
+$theme: mat.m2-define-light-theme((
+ color: (
+ primary: mat.define-palette(mat.$indigo-palette, 500),
+ ),
+ ...
+));
+
+html {
+ @include mat.core-theme($theme);
+ @include mat.button-theme($theme);
+ ...
+ @include mat.m2-theme($theme);
+ @include mat.system-classes();
+}
+```
+
+By using CSS variables and utility classes, you can avoid creating component-specific theme files
+and mixins that extract values from the `$theme` Sass map. For example, consider the following
+example of how styles used to be applied in custom components:
+
+```scss
+@use '@angular/material' as mat;
+@use 'sass:map';
+
+@mixin my-component-theme($theme) {
+ $foreground: map.get(mat.m2-get-color-config($theme), foreground);
+ $background: map.get(mat.m2-get-color-config($theme), background);
+ $primary: map.get(mat.m2-get-color-config($theme), primary);
+ $typography: mat.m2-get-typography-config($config-or-theme);
+
+ .widget-a {
+ background-color: mat.m2-get-color-from-palette($background, card);
+ color: mat.m2-get-color-from-palette($foreground, text);
+ @include mat.m2-typography-level($config, body-1);
+ }
+
+ .widget-b {
+ background-color: mat.m2-get-color-from-palette($primary, default);
+ color: mat.m2-get-color-from-palette($primary, default-contrast);
+ }
+}
+```
+
+By using the CSS variables, you can define these theme styles in your component's
+stylesheet and avoid creating a separate theme file or mixin:
+
+```scss
+.widget-a {
+ background-color: var(--mat-sys-surface);
+ color: var(--mat-sys-on-surface);
+ font: var(--mat-sys-body-medium);
+}
+
+.widget-b {
+ background-color: var(--mat-sys-primary);
+ color: var(--mat-sys-on-primary);
+}
+```
+
+Taking it one step further, you can alternatively use the utility classes to achieve the same styles
+in the component template:
+
+```html
+