New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@material/theme

Package Overview
Dependencies
Maintainers
15
Versions
1678
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@material/theme

The Material Components for the web theming system

14.0.0
latest
Source
npm
Version published
Weekly downloads
981K
0.2%
Maintainers
15
Weekly downloads
 
Created
Source

Theme

The Material Design color system can be used to create a color scheme that reflects your brand or style.

Design & API Documentation

  • Material Design guidelines: Color

Installation

npm install @material/theme

Usage

Color Scheme

You can define the theme color variables before importing any MDC Web components:

@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 styleDescription
primaryUsed for most text (e.g., text-primary-on-light)
secondaryUsed for text which is lower in the visual hierarchy (e.g., text-secondary-on-light)
hintUsed for text hints, such as those in text fields and labels (e.g., text-hint-on-light)
disabledUsed for text in disabled components and content (e.g., text-disabled-on-light)
iconUsed 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 propertyDescription
--mdc-theme-primaryThe theme primary color
--mdc-theme-secondaryThe theme secondary color
--mdc-theme-backgroundThe theme background color
--mdc-theme-surfaceThe theme surface color
--mdc-theme-on-primaryText color on top of a primary background
--mdc-theme-on-secondaryText color on top of a secondary background
--mdc-theme-on-surfaceText color on top of a surface background
--mdc-theme-text-<TEXT_STYLE>-on-lightText color for TEXT_STYLE on top of light background. Please see Text styles section.
--mdc-theme-text-<TEXT_STYLE>-on-darkText color for TEXT_STYLE on top of dark background. Please see Text styles section.
CSS Classes
CSS ClassDescription
mdc-theme--primarySets the text color to the theme primary color
mdc-theme--secondarySets the text color to the theme secondary color
mdc-theme--backgroundSets the background color to the theme background color
mdc-theme--surfaceSets the surface color to the theme surface color
mdc-theme--on-primarySets the text color to the theme on-primary color
mdc-theme--on-secondarySets the text color to the theme on-secondary color
mdc-theme--on-surfaceSets the text color to the theme on-surface color
mdc-theme--primary-bgSets the background color to the theme primary color
mdc-theme--secondary-bgSets the background color to the theme secondary color
mdc-theme--text-<TEXT_STYLE>-on-lightSets text to a suitable color for TEXT_STYLE on top of light background. Please see Text styles section.
mdc-theme--text-<TEXT_STYLE>-on-darkSets text to a suitable color for TEXT_STYLE on top of dark background. Please see Text styles section.

Sass Mixins, Variables, and Functions

MixinDescription
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 NameDescription
primaryThe theme primary color
secondaryThe theme secondary color
backgroundThe theme background color
surfaceThe theme surface color
text-<TEXT_STYLE>-on-lightTEXT_STYLE on top of a light background. Please see Text styles section.
text-<TEXT_STYLE>-on-darkTEXT_STYLE on top of a dark background. Please see Text styles section.
on-primaryA text/iconography color that is usable on top of primary color
on-secondaryA text/iconography color that is usable on top of secondary color
on-surfaceA 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

Keywords

material components
material design
theme

FAQs

Package last updated on 28 Apr 2022

Did you know?

Socket

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

Related posts

Socket and Seal Security Collaborate to Fix Critical npm Overrides Bug

Security News

Socket and Seal Security Collaborate to Fix Critical npm Overrides Bug

Socket and Seal Security collaborate to fix a critical npm overrides bug, resolving a three-year security issue in the JavaScript ecosystem's most popular package manager.

By Sarah Gooding  -  Mar 11, 2025