14.0.0 • Published 5 months ago

@material/theme v14.0.0

Weekly downloads
144,195
License
MIT
Repository
github
Last release
5 months ago

Theme

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

Design & API Documentation

Installation

npm install @material/theme

Usage

Color Scheme

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

$mdc-theme-primary: #fcb8ab;
$mdc-theme-secondary: #feeae6;
$mdc-theme-on-primary: #442b2d;
$mdc-theme-on-secondary: #442b2d;

@import "@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 mdc-button-filled-accessible. For more information, consult the documentation for each component.

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

A note about <TEXT_STYLE>, <TEXT_STYLE> represents the lowercase name of the text styles listed above, e.g. hint.

CSS Custom propertyDescription
--mdc-theme-primaryThe theme primary color
--mdc-theme-secondaryThe theme secondary color
--mdc-theme-backgroundThe theme background 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-text-<TEXT_STYLE>-on-lightText color for TEXT_STYLE on top of light background
--mdc-theme-text-<TEXT_STYLE>-on-darkText color for TEXT_STYLE on top of dark background

CSS Classes

A note about <TEXT_STYLE>, <TEXT_STYLE> represents the lowercase name of the text styles listed above, e.g. hint.

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--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--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
mdc-theme--text-<TEXT_STYLE>-on-darkSets text to a suitable color for TEXT_STYLE on top of dark background

Sass Mixins, Variables, and Functions

MixinDescription
mdc-theme-prop($property, $style, $important, $edgeOptOut)Applies a theme color or a custom color to a CSS property, optionally with !important. If $edgeOptOut is true and a theme color is passed, the style will be wrapped in a @supports clause to exclude the style in Edge to avoid issues with its buggy CSS variable support.

mdc-theme-prop Properties

The properties below can be used as the $style argument for the mdc-theme-prop mixin. Literal color values (e.g., rgba(0, 0, 0, .75)) may also be used instead.

A note about <TEXT_STYLE>, <TEXT_STYLE> represents the lowercase name of the text styles listed above, e.g. hint.

Property NameDescription
primaryThe theme primary color
secondaryThe theme secondary color
backgroundThe theme background color
text-<TEXT_STYLE>-on-lightTEXT_STYLE on top of a light background
text-<TEXT_STYLE>-on-darkTEXT_STYLE on top of a dark background
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

mdc-theme-luminance($color)

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

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

mdc-theme-contrast($back, $front)

Calculates the contrast ratio between two colors.

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

mdc-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 mdc-theme-tone(#9c27b0); // dark
@debug mdc-theme-tone(light);   // light

mdc-theme-contrast-tone($color)

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

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

mdc-theme-prop-value($property)

If $property is a literal color value (e.g., blue, #fff), it is returned verbatim. Otherwise, the value of the corresponding theme property (from $mdc-theme-property-values) is returned. If $property is not a color and no such theme property exists, an error is thrown.

This is mainly useful in situations where mdc-theme-prop cannot be used directly (e.g., box-shadow).

Unlike the mdc-theme-prop mixin, this function does not support CSS custom properties. It only returns the raw color value of the specified theme property.

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

@debug mdc-theme-prop-value(primary); // #3f51b5
@debug mdc-theme-prop-value(blue);    // blue

mdc-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 mdc-theme-prop-value
  • $text-style: Value must be one of primary, secondary, hint, disabled, icon (see $mdc-theme-text-colors)

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

@debug mdc-theme-accessible-ink-color(secondary); // rgba(0, 0, 0, .87) (text-primary-on-light)
@debug mdc-theme-accessible-ink-color(blue);      // white              (text-primary-on-dark)
@material/form-field@material/icon-button@material/list@material/image-list@material/linear-progress@material/floating-label@material/line-ripple@material/drawer@material/dialog@material/fab@material/elevation@material/data-table@material/circular-progress@material/checkbox@material/button@material/card@material/chips@material/banner@material/menu@material/menu-surface@material/notched-outline@material/select@material/top-app-bar@material/touch-target@material/tooltip@material/ripple@material/slider@material/textfield@material/snackbar@material/switch@material/tab@material/tab-indicator@material/tab-bar@material/rtl@material/shape@material/typography@material/radio@material/mwc-menu@material/segmented-buttonjuan-demo-app@zentek/button@zentek/switch@zentek/zenmdwrapper@beezydev/themeopenstamanagermrcwmaterial-components-web@everything-registry/sub-chunk-584ember-cli-mdc-themeember-material-componentsexecutable_htmlvue-compostvue-material-design-componentsjsonresume-theme-material-design@infinitebrahmanuniverse/nolb-_mate@material/grid-list@material/icon-toggle@material/mwc-circular-progress@material/focus@material/mwc-circular-progress-four-color@material/tabs@material/toolbar@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@material/mwc-linear-progressnang-mdc-test@mhamrah/svelte-material-uimwc-bundle@mcwv/theme@mcw/theme@mdcext/data-table@mdcext/date-picker@mdcext/input-dialog@mdcext/multiselect@mdcext/pagination@mdcext/treeview@mdc-stencil/theme@maicol07/mwa-card@maicol07/mwa-data-table@maicol07/mwc-cardmaterial-toolboxmaterial-components-elm-js-importsmdc-data-tablemdc-range-slidermdc-react-gumballmde-ultimatemdsc-navigation@labstack/data-table@jrg-material/button@jrg-material/material@jrg/ubuntu-ui@gmvdev/materials@mycause/ui@react-mdc/theme@react.material/theme@equinor/fusion-wc-theme@react-universal-dialogs/android
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

1.1.0

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.43.0

5 years ago

0.41.0

5 years ago

0.40.1

6 years ago

0.40.0

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.38.0

6 years ago

0.35.0

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.30.0

6 years ago

0.29.0

6 years ago

0.28.0

6 years ago

0.27.0

6 years ago

0.25.0

6 years ago

0.24.0

6 years ago

0.4.0

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.0

7 years ago

0.1.7

7 years ago

0.1.6

7 years ago

0.1.5

7 years ago

0.1.4

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago