@use "@material/theme" with (
  $primary: #fcb8ab,
  $secondary: #feeae6,
  $on-primary: #442b2d,
  $on-secondary: #442b2d,
);
@use "@material/button/mdc-button";

We suggest you follow the Web Content Accessibility Guidelines 2.0 when picking the values for on-primary, on-secondary, etc. These values should be accessible on top of the corresponding value, e.g. primary and secondary.

https://www.w3.org/TR/WCAG20

Advanced customization

Color scheme will only get you 80% of the way to a well-designed app. Inevitably there will be some components that do not work "out of the box". To fix problems with accessibility and design, we suggest you use our Sass mixins, such as button.filled-accessible(). For more information, consult the documentation for each component.

Text styles

The text styles (referred to as <TEXT_STYLE> below) used in the color system:

Text style	Description
`primary`	Used for most text (e.g., `text-primary-on-light`)
`secondary`	Used for text which is lower in the visual hierarchy (e.g., `text-secondary-on-light`)
`hint`	Used for text hints, such as those in text fields and labels (e.g., `text-hint-on-light`)
`disabled`	Used for text in disabled components and content (e.g., `text-disabled-on-light`)
`icon`	Used for icons (e.g., `text-icon-on-light`)

Here are the example usages of primary text style:

CSS Custom property: --mdc-theme-text-primary-on-light
Class name: mdc-theme--text-primary-on-light
Property name used in Sass: text-primary-on-light

Non-Sass customization

Only a very limited number of Material Design color customization features are supported for non-Sass clients. They are a set of CSS custom properties, and a set of CSS classes.

CSS Custom Properties

CSS Custom property	Description
`--mdc-theme-primary`	The theme primary color
`--mdc-theme-secondary`	The theme secondary color
`--mdc-theme-background`	The theme background color
`--mdc-theme-surface`	The theme surface color
`--mdc-theme-on-primary`	Text color on top of a primary background
`--mdc-theme-on-secondary`	Text color on top of a secondary background
`--mdc-theme-on-surface`	Text color on top of a surface background
`--mdc-theme-text-<TEXT_STYLE>-on-light`	Text color for TEXT_STYLE on top of light background. Please see Text styles section.
`--mdc-theme-text-<TEXT_STYLE>-on-dark`	Text color for TEXT_STYLE on top of dark background. Please see Text styles section.

CSS Classes

CSS Class	Description
`mdc-theme--primary`	Sets the text color to the theme primary color
`mdc-theme--secondary`	Sets the text color to the theme secondary color
`mdc-theme--background`	Sets the background color to the theme background color
`mdc-theme--surface`	Sets the surface color to the theme surface color
`mdc-theme--on-primary`	Sets the text color to the theme on-primary color
`mdc-theme--on-secondary`	Sets the text color to the theme on-secondary color
`mdc-theme--on-surface`	Sets the text color to the theme on-surface color
`mdc-theme--primary-bg`	Sets the background color to the theme primary color
`mdc-theme--secondary-bg`	Sets the background color to the theme secondary color
`mdc-theme--text-<TEXT_STYLE>-on-light`	Sets text to a suitable color for TEXT_STYLE on top of light background. Please see Text styles section.
`mdc-theme--text-<TEXT_STYLE>-on-dark`	Sets text to a suitable color for TEXT_STYLE on top of dark background. Please see Text styles section.

Sass Mixins, Variables, and Functions

Mixin	Description
`property($property, $value, $gss, $important)`	Applies a dynamic value to the specified property. The value may be a standard CSS value, a custom property Map, or a Material theme key.

Material theme keys with `theme.property()`

Material theme key names below can be used as the $value argument for the theme.property() mixin. Some keys are dynamic, and change context depending on other key values. Keys may also translate to custom properties for dynamic runtime theming.

Key Name	Description
`primary`	The theme primary color
`secondary`	The theme secondary color
`background`	The theme background color
`surface`	The theme surface color
`text-<TEXT_STYLE>-on-light`	TEXT_STYLE on top of a light background. Please see Text styles section.
`text-<TEXT_STYLE>-on-dark`	TEXT_STYLE on top of a dark background. Please see Text styles section.
`on-primary`	A text/iconography color that is usable on top of primary color
`on-secondary`	A text/iconography color that is usable on top of secondary color
`on-surface`	A text/iconography color that is usable on top of surface color

Custom properties with `theme.property()`

The theme.property() mixin also accepts a custom property Map for the $value argument. The map must contain a varname key with the name of the custom property, and an optional fallback key with the value of the custom property.

Use the @material/theme/custom-properties module to create custom property Maps.

For example, the following Sass...

@use "@material/theme";
@use "@material/theme/custom-properties";

.foo {
  @include theme.property(color, custom-properties.create(--foo-color, red));
}

...will produce the following CSS...

.foo {
  color: red;
  color: var(--foo-color, red);
}

The above output CSS will apply the fallback field's value for all supported browsers (including IE11) while allowing for CSS custom property use as a progressive enhancement. Browsers like IE11 that do not support CSS custom properties will apply the color: red; and ignore the color: var(--foo-color, red);. This argument type is intended for clients who need custom color application outside of the existing theme properties.

`theme.luminance($color)`

Calculates the luminance value (0 - 1) of a given color.

@debug theme.luminance(#9c27b0); // 0.11654

`theme.contrast($back, $front)`

Calculates the contrast ratio between two colors.

@debug theme.contrast(#9c27b0, #000); // 3.33071

`theme.tone($color)`

Determines whether the given color is "light" or "dark".

If the input color is a string literal equal to "light" or "dark", it will be returned verbatim.

@debug theme.tone(#9c27b0); // dark
@debug theme.tone(light);   // light

`theme.contrast-tone($color)`

Determines whether to use light or dark text on top of a given color.

@debug theme.contrast-tone(#9c27b0); // light

`theme.accessible-ink-color($fill-color, $text-style: primary)`

Returns an accessible ink color that has sufficient contrast against the given fill color.

Params:

$fill-color: Supports the same values as theme.prop-value
$text-style: Value must be one of primary, secondary, hint, disabled, icon (see $text-colors)

NOTE: This function is defined in _variables.scss instead of _functions.scss to avoid circular imports.

@debug theme.accessible-ink-color(secondary); // rgba(0, 0, 0, .87) (text-primary-on-light)
@debug theme.accessible-ink-color(blue);      // white              (text-primary-on-dark)

`theme.text-emphasis($emphasis)`

Returns opacity value for given emphasis.

Params:

$emphasis: Type of emphasis such as high, medium & disabled.

@debug theme.text-emphasis(high); // .87
@debug theme.text-emphasis(disabled); // .38

14.0.0 (2022-04-27)

Bug Fixes

button: update HCM shim to use the existing focus-ring (a657abb)
checkbox: Add explicit system color for checkmark in HCM. (8c4da22)
checkbox: move forced-colors theme out of static styles (bbd1126)
checkbox: Update checkbox theme styles mixin to accept css vars (c14e977)
chips: Fix typography selector in GMDC-Wiz chips theming (43c7d87)
datatable: Adjust data table last row border-radius to support setting row background-color. (ba78e87)
dialog: Render dividers in Firefox 94 on Windows HCM (fae6c65)
dialog: Set default z-index for close button in FloatingSheet dialog. (3366a71)
fab: Add focus ring in HCM. (d57ec74)
focus-ring: add 2d padding customizability, RTL bugfix (f81fb1d)
focus-ring: box-sizing bugfix to content-box. If box-sizing border-box is inherited the ring spacing will collapse. (e58552c)
focus-ring: ignore pointer events (3ef470e)
focus-ring: RTL bugfix (e00181e)
iconbutton: Fixed max width and height for high contrast mode focus ring on icon buttons. Display only in forced colors mode. (cf42927)
iconbutton: Set icon button ripple z-index to -1. (586e740)
list: Improve a11y for multi-select lists (9736ddc)
list: Remove conflicting validation for checkbox list in setEnabled (353ca7e)
list: Update lastSelectedIndex when toggling a checkbox range (dcba26f)
menusurface: Add a getOwnerDocument() method to MDCMenuSurfaceAdapter to provide a reference to the document that owns the menu surface DOM element. (3486659)
radio: Fix disabled state in Firefox Windows high contrast mode (23043ac)
radio: Modify theme styles Sass mixin validation to validate only keys (390220e)
select: Add border to select menu in HCM. (5d80969)
select: revert down/up arrow on anchor changing selected index (43d08ba)
slider: Fix bug where secondary click moves slider thumb. (3ab9565)
slider: Fix IE11 bug - unset is unsupported in IE. (f460e23)
slider: In updateUI, fix behavior to match jsdoc claim that when thumb param is undefined it updates both thumbs. Input attributes were not being updated at all. (cc4ed13)
slider: Make the slider errors easier to debug by providing all relevant values in the error message. (8687937)
snackbar: address Trusted Types violation (cbd9358)
tooltip: Adjusts logic in validateTooltipWithCaretDistances method. (3e30054)
typography: Fixes typography theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)
Remove /** @override */ tags from TypeScript code. (c3cdff0)
Simplify MDCAttachable interface to be any object (Function) that has attachTo. (05db65e)
Snackbar action button ripple color is applied to the ripple element. (4e66fb2)
Work around bug in Sass (037285f), closes sass/sass#3259
switch: Restore Firefox 94 HCM outlines (39cf14b)
textfield: Fix breaking tests due to no valid pointerId being associated with pointer events. (15db4f1)
tooltip: Only sends notification of a tooltip being hidden if showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)

Features

banner: Add disableAutoClose params for both banner actions to prevent the banner buttons from automatically closing the banner. Add adapter #notifyActionClicked method. (b094eaa)
chips: add focus ring styles (783f6fd)
chips: Added elevation tint layer color support in chips (c78ff04)
data-table: separate table structure into its own mixin (9f9d928)
dialog: Add styling for floating sheets (78305b6)
dialog: Add styling for floating sheets with content padding (3e20c1d)
Dialog: Adds an API to hide the header for GMDC Fullscreen Dialog in non-fullscreen mode (ab4aba1)
Dialog: Adds an API to set custom position for GMDC Dialog (ea9b5b4)
Dialog: Adds an API to set custom z-index for GMDC Dialog (96ea061)
focus-ring: added a new mixin so we can override just the focus-ring color (641ed08)
focus-ring: added a new mixin so we can override just the focus-ring radius (7321d62)
iconbutton: Add link icon button Sass. (9803d2d)
mdc-list: introduce selection change event (7d8ea46)
menu: allow preferentially opening surface below anchor (261f2db)
MenuSurface: Add opening event for menus. (53b3cad)
select: Add theming mixin boilerplate code to select (ae8a6a3)
select: Add validation getter methods. (bdf1d37)
select: Added theme mixins to MDC select (dcfe49c)
slider: Add minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)
slider: Add an option to hide focus styles after pointer interaction. (ec54d90)
slider: Keep the slider value indicator within the bounds of the slider if possible. (c047f7c)
state: make context aware (b2fe352)
switch: Add high contrast mode focus ring to switch (f31a833)
text-field: Add theming mixin boilerplate code to text-field (eb382f3)
text-field: Added theme mixins to MDC text field (344d528)
textfield: adding input-font-size mixin (207230e)
theme: allow custom property strings in theme.validate-theme() (4e372fb)
add new class and mixin for open state of a menu item (9a02b6e)
Indicate which thumb valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)
textfield: adding input-font-family mixin (991fb99)
Describe how to add child lists into a list item. (758ce31)

BREAKING CHANGES

MenuSurface: Adds #notifyOpening method to menu surface adapter.

PiperOrigin-RevId: 444830518

slider: Adds #getValueIndicatorContainerWidth method to slider adapter.

PiperOrigin-RevId: 419837612

Keywords

FAQs

What is @material/theme?

Is @material/theme popular?

Is @material/theme well maintained?

Package last updated on 28 Apr 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@material/theme

Theme

Design & API Documentation

Installation

Usage

Color Scheme

Advanced customization

Text styles

Non-Sass customization

CSS Custom Properties

CSS Classes

Sass Mixins, Variables, and Functions

Material theme keys with theme.property()

Custom properties with theme.property()

theme.luminance($color)

theme.contrast($back, $front)

theme.tone($color)

theme.contrast-tone($color)

theme.accessible-ink-color($fill-color, $text-style: primary)

theme.text-emphasis($emphasis)