This document intends to be a guide for theme authors on how to create a full Angular Material Theme color configuration (from scratch).
Unfortunately, documentation is rather lacking when going beyond the simple example provided by Angular Material.
While primary / accent / warn colors are easily comprehendable, and despite Angular Material publicly advertising that there is more than that to a theme (e. g. foreground palette - colors of text and icons), it fails to explain how to change these additional palettes and what they consist of.
This document aims to show how exactly one can create a full color configuration.
Since Angular Material is constantly evolving and subject to change, this is the status of this documentation:
Revision date: 2020-10-29
Angular Material Version: 10.x
- General Angular Material Theming Guide: https://material.angular.io/guide/theming
- Angular Material Source Code: https://github.com/angular/components/tree/master/src/material/core/theming
A complete color configuration object needs to be passed to the angular-material-theme mixin to create all CSS rules for Angular Material.
// Palette definition
// A palette is a SASS map with specific values.
$palette: (
default: color,
lighter: color,
darker: color,
// Contrast colors are used for example for text that is "on" a surface in this palette's color
// See examples in Material color system: "On" colors (https://material.io/design/color/the-color-system.html#color-theme-creation)
default-contrast: color,
lighter-contrast: color,
darker-contrast: color,
// Color of text that is to be displayed in this palette's color
// When using `mat-palette` this defaults to the `default` of this palette.
// Useful for when this palette's color is hard to read, so one can change it to become more legible.
text: color
)// Full color configuration definition
$angular-material-color-config-definition: (
// The primary palette
primary: Palette,
// The accent palette
accent: Palette,
// The palette that is used for **error** state like wrong input in a form field
warn: Palette,
// Whether this is a dark theme or not
is-dark: boolean,
// Colors for text and icons
foreground: (
// Foreground base color
// Used as a base *background color* in some elements (e. g. background of filled form fields, ...)
base: color,
// Divider color
divider: color,
// Disabled color used exclusively in:
// - Color of a disabled slide toggle bar
// - Disabled radio button
disabled: color,
// Disabled text of button-like elements
disabled-button: color,
// Disabled text color
disabled-text: color,
// Shadow color of elevated elements (like toolbar)
elevation: color,
// Hint text color, seldomly used as text color of disabled components
hint-text: color,
// Secondary text color used for example in sub headings
secondary-text: color,
// **Only** used for the dropdown icon of date in Material Datepicker
icon: color,
// General text *and* icon color
text: color,
// Angular Material slider customizations
slider-min: color, // slider circle color when on minimum value
slider-off: color, // color of the slider track
slider-off-active: color // color of the slider track when active (e. g. hover / focus)
),
// Colors for element backgrounds
background: (
// Default background color of a toolbar when not using any color palette (primary, accent, warn)
app-bar: color,
// General background color
background: color,
// Background color when hovering selectable elements like:
// - Select options
// - Selectable lists
// - Menu items
hover: color,
// Background color of cards
card: color,
// Background color of dialogs and sidenav (sidebar)
dialog: color,
// Angular Material Button customizations
disabled-button: color, // Disabled button background color
raised-button: color, // Default raised button background color when not using any color palette (primary, accent, warn)
focused-button: color, // Focussed button background color
// Angular Material Button Toggle customizations
selected-button: color, // Background color of selected button within a button toggle
selected-disabled-button: color, // Background color of a selected button within a disabled button toggle
disabled-button-toggle: color, // Background color of a button within a disabled button toggle
// Chip background color
unselected-chip: color,
// Disabled list item background color
disabled-list-option: color
)
)This example is from the original Angular Material source code of a Material Light Theme, as obtained with using mat-light-theme($primary, $accent, $warn) with all variables replaced with their actual values (except primary, accent and warn palettes).
Note: Some values in source code are actually not used anywhere and are omitted for clarity.
// Light theme full color configuration:
$material-light-theme: (
primary: $primary-left-out-for-readability,
accent: $accent-left-out-for-readability,
warn: $warn-left-out-for-readability,
is-dark: false,
foreground: (
base: black,
divider: rgba(black, 0.12),
disabled: rgba(black, 0.38),
disabled-button: rgba(black, 0.26),
disabled-text: rgba(black, 0.38),
elevation: black,
hint-text: rgba(black, 0.38),
secondary-text: rgba(black, 0.54),
icon: rgba(black, 0.54),
text: rgba(black, 0.87),
slider-min: rgba(black, 0.87),
slider-off: rgba(black, 0.26),
slider-off-active: rgba(black, 0.38),
),
background: (
app-bar: #F5F5F5,
background: #FAFAFA,
hover: rgba(black, 0.04),
card: white,
dialog: white,
disabled-button: rgba(black, 0.12),
raised-button: white,
focused-button: rgba(black, 0.12),
selected-button: #E0E0E0,
selected-disabled-button: #BDBDBD,
disabled-button-toggle: #EEEEEE,
unselected-chip: #E0E0E0,
disabled-list-option: #EEEEEE
)
);
@include angular-material-theme($material-light-theme);