@material/theme
Advanced tools
The Material Design color system can be used to create a color scheme that reflects your brand or style.
npm install @material/theme
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.
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.
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:
--mdc-theme-text-primary-on-lightmdc-theme--text-primary-on-lighttext-primary-on-lightOnly 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 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 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. |
| Mixin | Description |
|---|---|
prop($property, $style, $important) | Applies a theme color or a custom color to a CSS property, optionally with !important. |
mdc-theme-prop PropertiesThe 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.
| Property 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 |
mdc-theme-prop with CSS Custom PropertiesNote The Sass map
$styleargument is intended only for use with color mixins.
The mdc-theme-prop mixin also accepts a Sass map for the $style argument. The map must contain the following fields:
| Fields | Description |
|---|---|
varname | The name of a CSS custom property |
fallback | A fallback value for the CSS custom property |
For example, the following Sass...
@use "@material/theme";
.foo {
@include theme.prop(color, (
varname: --foo-color,
fallback: 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.
mdc-theme-luminance($color)Calculates the luminance value (0 - 1) of a given color.
@debug theme.luminance(#9c27b0); // 0.11654
mdc-theme-contrast($back, $front)Calculates the contrast ratio between two colors.
@debug 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 theme.tone(#9c27b0); // dark
@debug theme.tone(light); // light
mdc-theme-contrast-tone($color)Determines whether to use light or dark text on top of a given color.
@debug theme.contrast-tone(#9c27b0); // light
mdc-theme-prop-value($style)If $style is a color (a literal color value, currentColor, or a CSS custom property), it is returned verbatim.
Otherwise, $style is treated as a theme property name, and the corresponding value from $property-values
is returned. If this also fails, an error is thrown.
This is mainly useful in situations where prop cannot be used directly (e.g., box-shadow).
Unlike the 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.scssinstead of_functions.scssto avoid circular imports.
@debug theme.prop-value(primary); // #3f51b5
@debug 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 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.scssinstead of_functions.scssto 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)
mdc-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
6.0.0 (2020-04-22)
[@use](https://github.com/use) (098ae32)indeterminate checkbox (b273afa)select: HTML Markup significantly changed, see README; REMOVED adapter methods isSelectedTextFocused, getSelectedTextAttr, setSelectedTextAttr; ADDED adapter methods isSelectAnchorFocused, getSelectAnchorAttr, setSelectAnchorAttr; removed variables outlined-dense-label-position-y, icon-padding; added variables minimum-height-for-filled-label, filled-baseline-top, selected-text-height, anchor-padding-left, anchor-padding-left-with-leading-icon, anchor-padding-right.
text-field: Redundant mixins mdc-text-field-textarea-fill-color, mdc-text-field-textarea-stroke-color, mdc-text-field-fullwidth-bottom-line-color removed. Instead, use mdc-text-field-fill-color, mdc-text-field-outline-color, and mdc-text-field-bottom-line-color respectively to achieve the same effect.
textfield: mdc-text-field--dense and associated mixins/variables have been removed. Use the density() mixin instead.
textfield: removed the following variables: $input-padding, $input-padding-top, $input-padding-bottom, $outlined-input-padding-top, $outlined-input-padding-bottom, $input-border-bottom
linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.
linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.
typography: typography.baseline-top() and typography.baseline-bottom() are now private. Use typography.baseline() for containers and typography.text-baseline() for text with $top and $bottom params.
chips: The touch target and text now appear inside the primary action element. Please see the readme for markup changes.
textfield: filled text fields must include a <div class="mdc-text-field__ripple"></div>
textfield: Filled textfields will no longer show a floating label at certain densities. This can be overridden by setting $mdc-text-field-minimum-height-for-filled-label: 40px
chips: Both MDCChipAdapter and MDCChipSetAdapter have new methods. MDCChipSetFoundation event handlers now accept the corresponding chip event detail interface as the sole argument. The root property has been removed from the MDCChipRemovalEventDetail interface.
line-ripple: mdc-line-ripple-color() mixin has been renamed to mdc-line-ripple-active-color()
textfield: Default textfields must now specify mdc-text-field--filled. Disabled outlined textfields no longer have a shaded background. Height mixin no longer specifies a baseline override, use typography's baseline-top mixin.
Four variables and a mixin in mdc-textfield were renamed to use a mdc-text-field- prefix when depended on via @import (formerly mdc-required-text-field-label-asterisk_, now required-label-asterisk_).
textfield: icons must use .mdc-text-field__icon--leading or .mdc-text-field__icon--trailing classes. mdc-text-field-icon-color() mixin has been split into mdc-text-field-leading-icon-color() and mdc-text-field-trailing-icon-color().
switch: Added setNativeControlAttr method in mdc-switch adapter.
checkbox: remove event listener for 'change' and add event listener for 'click'.
$mdc-button-disabled-container-fill-color
renamed to $mdc-button-disabled-container-color.$edgeOptOut option from mdc-theme-prop() Sass mixin.FAQs
The Material Components for the web theming system
The npm package @material/theme receives a total of 869,239 weekly downloads. As such, @material/theme popularity was classified as popular.
We found that @material/theme demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
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.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."