Name	Name	Last commit message	Last commit date
parent directory ..
README.md	README.md
_constants.scss	_constants.scss
_functions.scss	_functions.scss
_mixins.scss	_mixins.scss
_variables.scss	_variables.scss
mdc-theme.scss	mdc-theme.scss
package.json	package.json

mdc-theme

MDC theme is a foundational module that provides theming to MDC-Web components, and also makes it available to developers as Sass functions and mixins, as CSS custom properties, and as a set of CSS classes.

The colors in this module are derived from the three theme colors in MDC-Web:

Primary: the primary color used in your application. This applies to a number of UI elements, such as app bars.
Accent: the accent color used in your application. This applies to UI elements such as FABs.
Background: the background color for your application. This is the color on top of which your UI is drawn.

When using the theme colors as background, it becomes important to choose a text color with sufficient contrast. In addition, it's important to consider the style of text:

Primary, used for most text.
Secondary, used for text which is lower in the visual hierarchy.
Hint, used for text hints (such as those in text fields and labels).
Disabled, used for text in disabled components and content.
Icon, used for icons.

Note: Don't confuse primary color with primary text. The former refers to the primary theme color, that is used to establish a visual identity and color many parts of your application. The latter refers to the style of text that is most prominent (low opacity, high contrast), and used to display most content.

The text contrast colors are automatically calculated at the Sass level and exposed as part of this module.

Installation

npm install --save @material/theme

Usage

Sass

Changing the theme colors

MDC Theme makes it quite easy to change the theme colors for your application, and have the changes apply to all MDC-Web components. Simply define the three theme color variables before importing mdc-theme or any MDC-Web components that rely on it:

$mdc-theme-primary: #9c27b0;
$mdc-theme-accent: #ffab40;
$mdc-theme-background: #fff;

@import "@material/theme/mdc-theme";

The correct text colors will automatically be calculated based on the provided theme colors.

mdc-theme-prop mixin

MDC Theme exports an mdc-theme-prop mixin, which can be used to apply a theme color to a property. The mixin takes the property name as the first parameter, and the desired color as the second one. It also has an optional boolean parameter for whether !important should be applied to the value.

For example, if you wanted to set the background of .foo to the primary color, and the text color to suit primary text on top of it:

@import "@material/theme/mixins";

.foo {
  @include mdc-theme-prop(background-color, primary);
  @include mdc-theme-prop(color, text-primary-on-primary);
}

This generates the following CSS:

.foo {
  background-color: #9c27b0;
  background-color: var(--mdc-theme-primary);
  color: #fff;
  color: var(--mdc-theme-text-primary-on-primary);
}

The generated code uses CSS custom properties for browsers that support it, with a fallback to a pre-processed static color if they don't. This enables runtime theming if CSS properties are available, in addition to the static theming described in the "Changing the theme colors" section.

Here is the full list of colors available to the mixin:

Theme colors

Class	Description
`primary`	The theme primary color.
`accent`	The theme accent color.
`background`	The theme background color.

Text on a theme primary color background

Class	Description
`text-primary-on-primary`	Primary text on top of a theme primary color background.
`text-secondary-on-primary`	Secondary text on top of a theme primary color background.
`text-hint-on-primary`	Hint text on top of a theme primary color background.
`text-disabled-on-primary`	Disabled text on top of a theme primary color background.
`text-icon-on-primary`	Icons on top of a theme primary color background.

Text on a theme accent color background

Class	Description
`text-primary-on-accent`	Primary text on top of a theme accent color background.
`text-secondary-on-accent`	Secondary text on top of a theme accent color background.
`text-hint-on-accent`	Hint text on top of a theme accent color background.
`text-disabled-on-accent`	Disabled text on top of a theme accent color background.
`text-icon-on-accent`	Icons on top of a theme accent color background.

Text on the theme background

Class	Description
`text-primary-on-background`	Primary text on top of the theme background.
`text-secondary-on-background`	Secondary text on top of the theme background.
`text-hint-on-background`	Hint text on top of the theme background.
`text-disabled-on-background`	Disabled text on top of the theme background.
`text-icon-on-background`	Icons on top of the theme background.

Text on a light-colored background (useful for custom backgrounds)

Class	Description
`text-primary-on-light`	Primary text on top of a light-colored background.
`text-secondary-on-light`	Secondary text on top of a light-colored background.
`text-hint-on-light`	Hint text on top of a light-colored background.
`text-disabled-on-light`	Disabled text on top of a light-colored background.
`text-icon-on-light`	Icons on top of a light-colored background.

Text on a dark-colored background (useful for custom backgrounds)

Class	Description
`text-primary-on-dark`	Primary text on top of a dark-colored background.
`text-secondary-on-dark`	Secondary text on top of a dark-colored background.
`text-hint-on-dark`	Hint text on top of a dark-colored background.
`text-disabled-on-dark`	Disabled text on top of a dark-colored background.
`text-icon-on-dark`	Icons on top of a dark-colored background.

mdc-theme-dark mixin

This mixin is mostly used for MDC-Web component development, and provides a standard way of applying dark themes to components. Note that mdc-theme-dark does not change any theme-wide background colors. Rather, mdc-theme-dark and its CSS classes are intended be used when certain sections or treatments of a page use a darker color as its background, where the default colors we use would not make sense.

mdc-theme-dark creates a suitable selector for a component, and applies the provided content inside of it:

.mdc-foo {
  color: black;

  @include mdc-theme-dark {
    color: white;
  }

  &__bar {
    background: black;

    @include mdc-theme-dark(".mdc-foo") {
      background: white;
    }
  }
}

.mdc-foo--disabled {
  opacity: .38;

  @include mdc-theme-dark(".mdc-foo", /* $compound: */ true) {
    opacity: .5;
  }
}

Note: If using the mixin on anything other than the base selector, you need to specify the base selector as a parameter. This ensures that the --theme-dark option is appended to the right class.

Note: If using the mixin with a modifier class, pass true for the second argument. This will tell the mixin to treat the selector it's being mixed into as a compound class rather than a descendant selector.

The above generates the following CSS:

.mdc-foo {
  color: black;
}
.mdc-foo--theme-dark, .mdc-theme--dark .mdc-foo {
  color: white;
}
.mdc-foo__bar {
  background: black;
}
.mdc-foo--theme-dark .mdc-foo__bar, .mdc-theme--dark .mdc-foo__bar {
  background: white;
}

.mdc-foo--disabled {
  opacity: .38;
}
.mdc-foo--theme-dark.mdc-foo--disabled,
.mdc-theme--dark .mdc-foo--disabled {
  opacity: .5;
}

A user could thus apply a dark theme to a component by either targeting it specifically:

<div class="mdc-foo mdc-foo--theme-dark"></div>

Or instead apply it to everything under a parent element, by using the mdc-theme--dark global modifier class:

<body class="mdc-theme--dark">
  <div class="mdc-foo"></div>
</body>

Color functions

MDC Theme defines several functions, used in the process of determining the correct contrast color for a given background.

mdc-theme-luminance

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

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

mdc-theme-contrast

Calculates the contrast ratio between two colors.

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

mdc-theme-light-or-dark

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

@debug mdc-theme-light-or-dark(#9c27b0); // light

CSS Classes

<span class="mdc-theme--primary">
  Some text in the primary color.
</span>

<span class="mdc-theme--accent-bg mdc-theme--text-primary-on-accent">
  Some text on an accent color background.
</span>

Note: These classes use !important on the values, since they're user-specified and are applied to ensure that a particular color gets used.

There are a number of CSS classes available for taking advantage of theming.

Theme color classes

These classes set either the text color or the background color to one of the theme colors.

Class	Description
`mdc-theme--primary`	Sets the text color to the theme primary color.
`mdc-theme--accent`	Sets the text color to the theme accent color.
`mdc-theme--background`	Sets the background color to the theme background color.
`mdc-theme--primary-bg`	Sets the background color to the theme primary color.
`mdc-theme--accent-bg`	Sets the background color to the theme accent color.

Text colors for contrast

These classes set the text color to a suitable color to be used on top of a given background. The color to be used depends on two criteria: the background color (namely, whether it's light or dark) and the text style.

Text on a theme primary color background

Class	Description
`mdc-theme--text-primary-on-primary`	Set text to suitable color for primary text on top of a theme primary color background.
`mdc-theme--text-secondary-on-primary`	Set text to suitable color for secondary text on top of a theme primary color background.
`mdc-theme--text-hint-on-primary`	Set text to suitable color for hint text on top of a theme primary color background.
`mdc-theme--text-disabled-on-primary`	Set text to suitable color for disabled text on top of a theme primary color background.
`mdc-theme--text-icon-on-primary`	Set text to suitable color for icons on top of a theme primary color background.

Text on a theme accent color background

Class	Description
`mdc-theme--text-primary-on-accent`	Set text to suitable color for primary text on top of a theme accent color background.
`mdc-theme--text-secondary-on-accent`	Set text to suitable color for secondary text on top of a theme accent color background.
`mdc-theme--text-hint-on-accent`	Set text to suitable color for hint text on top of a theme accent color background.
`mdc-theme--text-disabled-on-accent`	Set text to suitable color for disabled text on top of a theme accent color background.
`mdc-theme--text-icon-on-accent`	Set text to suitable color for icons on top of a theme accent color background.

Text on the theme background

Class	Description
`mdc-theme--text-primary-on-background`	Set text to suitable color for primary text on top of the theme background.
`mdc-theme--text-secondary-on-background`	Set text to suitable color for secondary text on top of the theme background.
`mdc-theme--text-hint-on-background`	Set text to suitable color for hint text on top of the theme background.
`mdc-theme--text-disabled-on-background`	Set text to suitable color for disabled text on top of the theme background.
`mdc-theme--text-icon-on-background`	Set text to suitable color for icons on top of the theme background.

Text on a light-colored background (useful for custom backgrounds)

Class	Description
`mdc-theme--text-primary-on-light`	Set text to suitable color for primary text on top of a light-colored background.
`mdc-theme--text-secondary-on-light`	Set text to suitable color for secondary text on top of a light-colored background.
`mdc-theme--text-hint-on-light`	Set text to suitable color for hint text on top of a light-colored background.
`mdc-theme--text-disabled-on-light`	Set text to suitable color for disabled text on top of a light-colored background.
`mdc-theme--text-icon-on-light`	Set text to suitable color for icons on top of a light-colored background.

Text on a dark-colored background (useful for custom backgrounds)

Class	Description
`mdc-theme--text-primary-on-dark`	Set text to suitable color for primary text on top of a dark-colored background.
`mdc-theme--text-secondary-on-dark`	Set text to suitable color for secondary text on top of a dark-colored background.
`mdc-theme--text-hint-on-dark`	Set text to suitable color for hint text on top of a dark-colored background.
`mdc-theme--text-disabled-on-dark`	Set text to suitable color for disabled text on top of a dark-colored background.
`mdc-theme--text-icon-on-dark`	Set text to suitable color for icons on top of a dark-colored background.

CSS Custom properties

MDC Theme defines a number of custom properties to make theming in pure CSS possible, if you have access to CSS custom properties in your system.

Note: Unfortunately, due to the limitations of custom CSS properties, it's not currently possible to automatically calculate the correct text colors to use, based on the chosen theme colors. These will all need to be set manually.

Theme colors

Custom property	Description
`--mdc-theme-primary`	The theme primary color.
`--mdc-theme-accent`	The theme accent color.
`--mdc-theme-background`	The theme background color.

Text on a theme primary color background

Custom property	Description
`--mdc-theme-text-primary-on-primary`	Primary text on top of a theme primary color background.
`--mdc-theme-text-secondary-on-primary`	Secondary text on top of a theme primary color background.
`--mdc-theme-text-hint-on-primary`	Hint text on top of a theme primary color background.
`--mdc-theme-text-disabled-on-primary`	Disabled text on top of a theme primary color background.
`--mdc-theme-text-icon-on-primary`	Icons on top of a theme primary color background.

Text on a theme accent color background

Custom property	Description
`--mdc-theme-text-primary-on-accent`	Primary text on top of a theme accent color background.
`--mdc-theme-text-secondary-on-accent`	Secondary text on top of a theme accent color background.
`--mdc-theme-text-hint-on-accent`	Hint text on top of a theme accent color background.
`--mdc-theme-text-disabled-on-accent`	Disabled text on top of a theme accent color background.
`--mdc-theme-text-icon-on-accent`	Icons on top of a theme accent color background.

Text on the theme background

Custom property	Description
`--mdc-theme-text-primary-on-background`	Primary text on top of the theme background.
`--mdc-theme-text-secondary-on-background`	Secondary text on top of the theme background.
`--mdc-theme-text-hint-on-background`	Hint text on top of the theme background.
`--mdc-theme-text-disabled-on-background`	Disabled text on top of the theme background.
`--mdc-theme-text-icon-on-background`	Icons on top of the theme background.

Text on a light-colored background (useful for custom backgrounds)

Custom property	Description
`--mdc-theme-text-primary-on-light`	Primary text on top of a light-colored background.
`--mdc-theme-text-secondary-on-light`	Secondary text on top of a light-colored background.
`--mdc-theme-text-hint-on-light`	Hint text on top of a light-colored background.
`--mdc-theme-text-disabled-on-light`	Disabled text on top of a light-colored background.
`--mdc-theme-text-icon-on-light`	Icons on top of a light-colored background.

Text on a dark-colored background (useful for custom backgrounds)

Custom property	Description
`--mdc-theme-text-primary-on-dark`	Primary text on top of a dark-colored background.
`--mdc-theme-text-secondary-on-dark`	Secondary text on top of a dark-colored background.
`--mdc-theme-text-hint-on-dark`	Hint text on top of a dark-colored background.
`--mdc-theme-text-disabled-on-dark`	Disabled text on top of a dark-colored background.
`--mdc-theme-text-icon-on-dark`	Icons on top of a dark-colored background.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mdc-theme

mdc-theme

README.md

mdc-theme

Installation

Usage

Sass

Changing the theme colors

mdc-theme-prop mixin

Theme colors

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)

mdc-theme-dark mixin

Color functions

mdc-theme-luminance

mdc-theme-contrast

mdc-theme-light-or-dark

CSS Classes

Theme color classes

Text colors for contrast

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)

CSS Custom properties

Theme colors

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)

Files

mdc-theme

Directory actions

More options

Directory actions

More options

Latest commit

History

mdc-theme

Folders and files

parent directory

README.md

mdc-theme

Installation

Usage

Sass

Changing the theme colors

mdc-theme-prop mixin

Theme colors

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)

mdc-theme-dark mixin

Color functions

mdc-theme-luminance

mdc-theme-contrast

mdc-theme-light-or-dark

CSS Classes

Theme color classes

Text colors for contrast

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)

CSS Custom properties

Theme colors

Text on a theme primary color background

Text on a theme accent color background

Text on the theme background

Text on a light-colored background (useful for custom backgrounds)

Text on a dark-colored background (useful for custom backgrounds)