Material Theme Creator

How to use themes correctly on your site.

PLUS Converting Angular Material themes to CSS Custom Properties (Variables)

Full Documentation: artik-man.github.io/material-theme-creator

Contents

• How it works?
• How to use Material Theme Creator
  • Pure CSS use
  • Use with SCSS
  • Use with Angular Material
• Description of functionality

How it works?

We use CSS Custom Properties and HSL color space for dynamic theme colors’ calculation.

:root {
    --primary-h: 260;
    --primary-s: 80%;
    --primary-l: 40%;
    --primary: hsl(var(--primary-h), var(--primary-s), var(--primary-l));
}

We have already created a color consisting of H, S and L components of the HSL color space. But how can we create the whole theme palette? We need to do some calculations for this.

 :root {
    --primary-400: hsl(
            calc(var(--primary-h) * var(--h-400)),
            calc(var(--primary-s) * var(--s-400)),
            calc(var(--primary-l) * var(--l-400))
    );
    --primary-500: hsl(
            calc(var(--primary-h) * var(--h-500)),
            calc(var(--primary-s) * var(--s-500)),
            calc(var(--primary-l) * var(--l-500))
    );
}

In fact, the code is a bit more complicated, but this piece of code is enough to understand the algorithm.

How to use Material Theme Creator

1. Pure CSS use

You can download your theme by clicking on the button "Download theme" which is located above. Then you should include it to your page in any convenient way. For example:

<link href="./my-theme.css" rel="stylesheet">

After that you can create the second theme style:

.second-theme {
    --my-theme-h: 190;
    --my-theme-s: 80;
    --my-theme-l: 40;
    --my-theme-contrast-threshold: 50%;
}

And you can apply the theme with some button:

const changeThemeButton = document.querySelector('button.change-theme-btn');

changeThemeButton.addEventListener('click', () => {
    document.documentElement.classList.toggle('second-theme');
});

How can you use theme on your elements? 14 theme colors will be available for you. For each of these colors you will have access to one contrasting color. See example:

button {
    background-color: var(--my-theme);
    color: var(--my-theme-contrast);
}

button:hover {
    background-color: var(--my-theme-700);
    color: var(--my-theme-700-contrast);
}

How can we set transparency of the color? You can adjust it yourself:

div {
    background-color: hsla(
            var(--my-theme-500-h),
            var(--my-theme-500-s),
            var(--my-theme-500-l),
            62% /* alpha */
    );
}

2. Use with SCSS

You can have more options to manage the theme if you use SCSS.

Installation:

npm install material-theme-creator

Use:

@use "~material-theme-creator/core" as mtc;

// root variables initializing
@include mtc.init();

body {
  // Creating a theme based on some color
  // Passing arguments to the mixin:
  //   1. theme name
  //   2. some color
  //   3. contrast threshold (for fonts)
  @include mtc.create-variables-from-color('primary', #cc3300, 50%);
}

body.secondary-theme {
  @include mtc.update-theme('primary', #6200ee, 55%);
}

button {
  color: mtc.color-contrast('primary');
  background-color: mtc.color('primary');

  &:hover {
    color: mtc.color-contrast('primary', 700);
    background-color: mtc.color('primary', 700, 92%);
  }
}

3. Use with Angular Material

You can use ngx-mtc module to convert Angular Material themes to use CSS Custom Properties.

Installation:

npm install material-theme-creator

Setup

@use '~@angular/material' as mat;
@use "~material-theme-creator/ngx-mtc" as ngx-mtc;

@include mat.core();
@include ngx-mtc.init();

$primary-map: ngx-mtc.create-theme-map('primary');
$accent-map: ngx-mtc.create-theme-map('accent');
$warn-map: ngx-mtc.create-theme-map('warn');

Set up main theme

Use ngx-mtc.create-variables-from-color to create theme from one color. In this case, each theme will consist of just a few lines of code.

You can also use ngx-mtc.create-variables-from-map to create theme from color-map like mat.$red-palette

WARNING: The mat.define-light-theme and mat.define-dark-theme mixins generate a lot of CSS code for each theme. Use this as sparingly as possible.

:root {
  --is-dark-theme: 1; // Is dark theme? 1 or 0;
  @include ngx-mtc.theme-base(); // Creates base colors

  // Creates theme colors
  @include ngx-mtc.create-variables-from-color('primary', #009688, 38%); // can update
  @include ngx-mtc.create-variables-from-color('accent', #2196f3, 57%); // can update
  @include ngx-mtc.create-variables-from-map('warn', mat.$red-palette); // can not update this theme
}

$primary-palette: mat.define-palette($primary-map);
$accent-palette: mat.define-palette($accent-map);
$warn-palette: mat.define-palette($warn-map);

// Custom theme
$theme: ngx-mtc.custom-theme($primary-palette, $accent-palette, $warn-palette);

// Creates Angular Material Theme
@include mat.all-component-themes($theme);

Set up second theme

 html.second-theme {
  --is-dark-theme: 0;
  @include ngx-mtc.update-theme('primary', #142148, 45%);
  @include ngx-mtc.update-theme('accent', #658e14, 50%);
}

How to use

Use standard Angular material mat.color and mat.contrast mixins to extract specific colors from the theme.

button {
  color: mat.contrast($primary-map, 500);
  background-color: mat.color($primary-map, 500);

  &:hover {
    color: mat.contrast($primary-map, 700);
    background-color: mat.color($primary-map, 700, 92%);
  }
}

Description of functionality

Core

@use '~material-theme-creator/core' as mtc;

init()

Library Initialization

@include mtc.init()

create-variables-from-color($theme-name, $color, $contrast-threshold: 50%)

Creates CSS Custom Properties for mat-palette from one color

:root {
  @include mtc.create-variables-from-color('primary', #f00, 45%);
}

Returns CSS Custom Properties:

:root {
    --primary: hsl(...);
    --primary-50: hsl(...);
    --primary-50-contrast: hsl(...);
    --primary-100: hsl(...);
    --primary-100-contrast: hsl(...);
    /*...*/
    --primary-A700: hsl(...);
    --primary-A700-contrast: hsl(...);
}

update-theme($theme-name, $color, $contrast-threshold: 50%)

Update theme

.second-theme {
  @include mtc.update-theme('primary', hsl(212, 95%, 80%), 55%);
}

Returns CSS Custom Properties: Hue, Lightness, Saturation for CSS Color and contrast threshold for this theme

.second-theme {
    --primary-h: 212;
    --primary-s: 95;
    --primary-l: 80;
    --primary-contrast-threshold: 50%;
}

color($theme-name, $index: 500, $alpha: 100%)

Get theme color

button {
  background: mtc.color('primary', 400, 70%);
}

color-contrast($theme-name, $index: 500)

Get theme contrast color

button {
  color: mtc.color-contrast('primary', 400);
}

theme-component($min:0, $max:100, $unit: 1, $dark-theme-variable: --is-dark-theme)

Returns a value according to the current theme (light/dark) Based on CSS Custom Properties

main {
  background: hsl(123deg, 85%, #{mtc.theme-component(34, 72, 1%)});
}

In light theme:

main {
    background: hsl(123deg, 85%, 34%);
}

In dark theme:

main {
    background: hsl(123deg, 85%, 72%);
}

theme-color($light, $dark, $dark-theme-variable: --is-dark-theme)

Returns a color according to current theme (light/dark) Based on CSS Custom Properties

main {
  background: mtc.theme-color(#fff, #333);
}

In light theme:

main {
    background: #fff;
}

In dark theme:

main {
    background: #333;
}

NGX

@use '~material-theme-creator/ngx-mtc' as ngx-mtc;

init()

Library Initialization

@include ngx-mtc.init();

create-variables-from-color($theme-name, $color, $contrast-threshold: 50%)

Creates CSS Custom Properties for mat-palette from one color

:root {
  @include ngx-mtc.create-variables-from-color('primary', #f00, 45%);
}

Returns CSS Custom Properties:

:root {
    --primary: hsl(...);
    --primary-50: hsl(...);
    --primary-50-contrast: hsl(...);
    --primary-100: hsl(...);
    --primary-100-contrast: hsl(...);
    /*...*/
    --primary-A700: hsl(...);
    --primary-A700-contrast: hsl(...);
}

create-variables-from-map($theme-name, $theme-map)

Creates CSS Custom Properties for mat-palette from mat-palette

You can use theme-map from ~@angular/material/core/theming/_palette (e.g. $red-palette or $pink-palette...)

  @include ngx-mtc.create-variables-from-map('primary', mat.$red-palette);

Returns CSS Custom Properties:

:root {
    --primary: hsl(...);
    --primary-50: hsl(...);
    --primary-50-contrast: hsl(...);
    --primary-100: hsl(...);
    --primary-100-contrast: hsl(...);
    /*...*/
    --primary-A700: hsl(...);
    --primary-A700-contrast: hsl(...);
}

theme-base()

Creates base colors CSS Variables for angular material theme.

:root {
  @include ngx-mtc.theme-base();
}

Returns CSS Custom Properties:

:root {
    --mtc-background-status-bar: hsl(...);
    --mtc-background-app-bar: hsl(...);
    --mtc-background-background: hsl(...);
    --mtc-background-hover: hsl(...);
    /*...*/
    --mtc-foreground-slider-off-active: hsl(...);

update-theme($theme-name, $color, $contrast-threshold: 50%)

Update theme

.second-theme {
  @include ngx-mtc.update-theme('primary', hsl(212, 95%, 80%), 55%);
}

Returns CSS Custom Properties: Hue, Lightness, Saturation for CSS Color and contrast threshold for this theme

.second-theme {
    --primary-h: 212;
    --primary-s: 95;
    --primary-l: 80;
    --primary-contrast-threshold: 50%;
}

create-theme-map($theme-name)

Creates a theme-map for use in Angular Material

$primary-map: ngx-mtc.create-theme-map('primary');

custom-theme($primary, $accent, $warn)

Set base colors CSS Variables into angular material

$primary-palette: mat.define-palette($primary-map);
$accent-palette: mat.define-palette($accent-map);
$warn-palette: mat.define-palette($warn-map);

$theme: ngx-mtc.custom-theme($primary-palette, $accent-palette, $warn-palette);

color($theme-name, $index: 500, $alpha: 100%)

Get theme color

button {
  background: ngx-mtc.color('primary', 400, 70%);
}

color-contrast($theme-name, $index: 500)

Get theme contrast color

button {
  color: ngx-mtc.color-contrast('primary', 400);
}

theme-color($light, $dark, $dark-theme-variable: --is-dark-theme)

Returns a color according to current theme (light/dark) Based on CSS Custom Properties

main {
  background: ngx-mtc.theme-color(#fff, #333);
}

In light theme:

main {
    background: #fff;
}

In dark theme:

main {
    background: #333;
}