Angular Material Theming

Get Starting

Installation

$npm install @hysalim/theming

Angular

In angular.json add

"projects": {
  "architect": {
    "build": {
      "options": {
        /** Add properties */

        "stylePreprocessorOptions": {
          "includePaths": [
            "node_modules/
          ]
        }
        .......................................
      }
    }
  }
}

SCSS

Import SCSS in your style sheet

@use "@hysalim/theming/theme";

TypeScript

Import service in appModule

@import {MatThemingModule, MatThemingConfig} from '@hysalim/theming';

const theme: MatThemingConfig[] = [
  {name: 'default', dataClass: ''}
];

@NgModule({
  ................
  MatThemingModule.forRoot(theme)
  ................
})
export class AppModule { }

Usage

To set multiple themes within your app

SCSS

In your stylesheet

@use "@hysalim/theming/theme" with (
  theme-list: (
    default: (
      primary: (color: blue),
      accent: (color: teal)
    ),
    secondary-theme: (
      primary: (color: teal, default: 600)
    )
  )
);

Each theme you create is based on a basic theme. You don't have to write down all the settings

$_base-theme: (
  light-color: #FFF,
  dark-color: #000,
  light-status-bar: #E0E0E0,
  dark-status-bar: black,
  primary: (color: #6200EE, default: 500, lighter: 100, darker: 700, text: 500),
  accent: (color: #018786, default: 500, lighter: 100, darker: 700, text: 500),
  warn: (color: #B00020, default: 500, lighter: 100, darker: 700, text: 500),
  darkBackground: #121212,
  darkThemeMixToPrimary: "true",
  darkMaterialReference: "true"
) !default;

Key name	Description
light-color	The base of light color (use for background, surface,...)
dark-color	The base of dark color (use to front color, icon, ...)
light-status-bar	The color of status bar in light mode
dark-status-bar	The color of status bar in dark mode
primary, accent and warn	The base color of the palette colors. color is a color base, default is the default color of palette color, lighter is the light color of the palette, darker is the dark color of the palette and text is the text color of the palette.
darkBackground	The background color of the dark mode
darkThemeMixToPrimary	The background color is mixed with the primary color ("true" or "false")
darkMaterialReference	True if you want to use Material specification. Modifie elevation, image and primary palette color in dark mode.

TypeScript

Import service in appModule

@import {MatThemingModule, MatThemingConfig} from '@hysalim/theming';

const theme: MatThemingConfig[] = [
  {name: 'default', dataClass: ''},
  {name: 'Name of my Secondary Theme', dataClass: 'secondary-theme'}
];

@NgModule({
  ................
  MatThemingModule.forRoot(theme)
  ................
})
export class AppModule { }

In app.component.ts

import { Component } from '@angular/core';
import { MatThemingService } from '@hysalim/theming';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {
  title = 'documentation';

  constructor(public theme: MatThemingService) {}
}

HTML

<mat-menu #menu="matMenu">
    <button mat-menu-item *ngFor="let item of theme.themeList" (click)="theme.setMatTheme(item.dataClass)">
      <span>{{item.name}}</span>
    </button>
  </mat-menu>

Mixins and functions

Luminance

theme.luminance($color)

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

@debug theme.luminance(#9C27B0); //return 0.116554

Contrast

theme.contrast($background, $front)

Calculates the contrast ratio between two colors.

@debug theme.contrast(#9C27B0, #000); // return 3.33071

Note:
Minimum contrast recommanded by Material Theming is 3.1

Tone

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); // return dark
@debug(light); // return light

Tone contrast

theme.contrast-tone($color)

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

@debug theme.contrast-tone(#9C27B0); // return light

Accessible text color

theme.accessible-ink-color($color, $light-color: #FFF, $dark-color: #000)

Returns an accessible ink color that has sufficient contrast against the given color fill.

@include theme.accessible-ink-color(bleu); // return color: #FFF

Custom properties

theme.property($property,$value-of-property-values)

Keys of palette colors

Key Name	Description
primary-default	The theme of primary default color
primary-lighter	The theme of primary lighter color
primary-darker	The theme of primary darker color
primary-text	The theme of primary text color
primary-50 primary-100 or other hue	The theme of primary hue 50 color or other hue color
primary-contrast-default	The theme of primary contrast default color
primary-contrast-lighter	The theme of primary contrast lighter color
primary-contrast-darker	The theme of primary contrast darker color
primary-contrast-text	The theme of primary contrast text color
primary-contrast-50 primary-contrast-100 or other hue	The theme of primary contrast hue 50 color or other contrast hue color

Note:
Idem for other palette:

• accent
• warn

Keys of foreground

Key name	Description
base	The theme of base color
disabled	The theme of disabled color
disabled-button	The theme of disabled button color
elevation	The theme of elevation color (black)
secondary-text	The theme of secondary text color
icon	The theme of icon color
text	The theme of text color
slider-off	The theme of slider off color
slider-off-active	The theme of slider off active color
Keys of background
Key name	Description
--------	-----------
status-bar	The theme of status bar color
app-bar	The theme of application bar color
background	The theme of background color
hover	The theme of hover color
surface	The theme of surface color
disabled-button-background	The theme of disabled background button color
focused	The theme of focused color
selected	The theme of selected color
selected-disabled	The theme of selected disabled color
disabled-component	The theme of disabled component color
unselect-chip	The theme of unselected chip color
tooltip	The theme of tooltip color

@use "@hysalim/theming/theme";

.foo {
  @include theme.property(background, primary-red-500);
}
/// return in CSS
.foo {
  background: red;
  background: var(--mat-theme-red-500, red);
}

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 @hysalim/theme/helper/custom-properties module to create custom property Maps.

@use "@hysalim/theming/theme";
@use "@hysalim/theming/theme/helper/custom-properties";

.foo {
  @include theme.property(color, custom-properties.create(--foo-color, red));
}
/// return in CSS
.foo {
  background: red;
  background: var(--foo-color, red);
}