Documentation
Guides
Customization

## Theming

Since Fuse uses Angular Material as its primary UI library, it also uses the Angular Material Theming with a twist.

Rather than using Angular Material's default theming process, Fuse incorporates that into the Tailwind's build process. This way, you can configure your application using Tailwind's configuration file and things like colors, font families, breakpoints and etc. will be carried over and applied to the Angular Material components.

You can also create color themes using Tailwind's configuration and they will also be carried over and used for building Angular Material themes. Here's an example theme configuration from Tailwind's configuration:

// tailwind.config.js /** * Themes */ const themes = { // Default theme is required for theming system to work correctly 'default': { primary : { ...colors.indigo, DEFAULT: colors.indigo[600] }, accent : { ...colors.slate, DEFAULT: colors.slate[800] }, warn : { ...colors.red, DEFAULT: colors.red[600] }, 'on-warn': { 500: colors.red['50'] } }, // Rest of the themes will use the 'default' as the base theme // and extend them with their given configuration 'brand' : { primary: customPalettes.brand }, 'teal' : { primary: { ...colors.teal, DEFAULT: colors.teal[600] } }, 'purple' : { primary: { ...colors.purple, DEFAULT: colors.purple[600] } }, 'amber' : { primary: colors.amber } };

Here's the general structure of a theme configuration:

THEME_NAME: { primary : { ... }, accent : { ... }, warn : { ... }, 'on-primary': { ... } 'on-accent' : { ... } 'on-warn' : { ... } }

- primary, accent, warn

  These are the 3 main color palettes of the theme. They must be a Tailwind color palette. If DEFAULT is provided, that will become the main color of that palette otherwise the 500 hue level from the same palette will be used as the DEFAULT.

- on-primary, on-accent, on-warn

  These are the 3 main contrasting color palettes of the theme. They can be either a complete or a partial Tailwind color palette. By default, Fuse will automatically generate contrasting colors using the colors from "Primary", "Accent" and "Warn" palettes but for some reason, if you want more control over the contrasting colors, you can use these objects to customize them.

Angular Material library uses 3 main color palettes and their contrasting colors to theme their components. Here we basically moved that configuration (in a customized and simplified way) into the Tailwind.

In order to have a complete understanding how Angular Material components are themed, you can check their official guides here: https://material.angular.io/guide/theming

Let's break down the 'default' theme configuration. This one is required for entire theming system and Fuse to work correctly:

// tailwind.config.js 'default': { // Here we define the "Primary" palette for the default theme. // It uses the default "indigo" color palette from Tailwind's default // color palettes and sets the 600 hue level as the DEFAULT color. // If you omit the DEFAULT, 500 hue level will become the DEFAULT. primary : { ...colors.indigo, DEFAULT: colors.indigo[600] }, // Here we define the "Accent" palette for the default theme. // It uses the default "slate" color palette from Tailwind's default // color palettes and sets the 800 hue level as the DEFAULT color. accent : { ...colors.slate, DEFAULT: colors.slate[800] }, // Here we define the "Warn" palette for the default theme. // It uses the default "red" color palette from Tailwind's default // color palettes and sets the 600 hue level as the DEFAULT color. warn : { ...colors.red, DEFAULT: colors.red[600] }, // Since we want Fuse to automatically generate contrasting colors // for "Primary" and "Accent" palettes, we omit "on-primary" and // "on-accent" objects. // Here we define the "on-warn" palette. As you can see, it's not a // complete palette but a partial one. Fuse will actually automatically // generate the contrasting colors for "Warn" palette as well but it will // also merge the below configuration so the contrasting color for // red.500 will be red.50 from the same palette. 'on-warn': { 500: colors.red['50'] } }

Let's break down the rest of the theme configuration:

// tailwind.config.js // All themes will inherit the configuration from the "default" theme so you // can only change the palettes you want to change. Rest will be the same as // the "default" palette. // Here we have a theme called "brand". This theme uses a custom Tailwind // color palette called "brand". You can either manually create custom color // palettes or use our custom helper method to generate them from a single // color. 'brand' : { primary: customPalettes.brand }, // Here we have a custom theme called "teal". This one only defines the // "Primary" palette and uses the "Teal" palette from the default Tailwind // palettes. 'teal' : { primary: { ...colors.teal, DEFAULT: colors.teal[600] } }, // Here we have a custom theme called "purple". This one only defines the // "Primary" palette and uses the "Purple" palette from the default Tailwind // palettes. 'purple' : { primary: { ...colors.purple, DEFAULT: colors.purple[600] } }, // Here we have a custom theme called "amber". This one only defines the // "Primary" palette and uses the "Amber" palette from the default Tailwind // palettes. 'amber' : { primary: colors.amber }

## Color palettes

By default, Tailwind provides lots of color palettes so you can always use them to create themes.

If you have a different color that you want to use, like a brand color or a custom hand picked one, you must generate a Tailwind-like color palette in order to be able to generate themes with. There are couple ways of creating such palettes;

1. You can create them by hand. Though this gives you complete freedom, it is by far the hardest one especially if you don't have any experience with colors and their relations.
2. You can use online tools to generate Tailwind color palettes. They usually do a decent job for creating palettes but they could be a little off in some cases.
3. You can use our custom `generatePalette()` helper method to create palettes either from a single color, or from multiple colors.

### `generatePalette()`

This custom helper method allows you to generate Tailwind-like palettes from either a single color or multiple colors:

// tailwind.config.js const generatePalette = require(path.resolve(__dirname, ('src/@fuse/tailwind/utils/generate-palette'))); /** * Custom palettes * * Uses the generatePalette helper method to generate * Tailwind-like color palettes automatically */ const customPalettes = { brand : generatePalette('#F50057'), myColorPalette: generatePalette({ 200: '#c7d2fe', 500: '#6366f1', 800: '#3730a3', }) };

Usually, if you are working on an app by yourself, both designing and developing it, generating a complete Tailwind-like palette from a single color is a great option. But that's not always the case and most palette generators only give you an option to generate a palette using a single color. That becomes problematic if you have more than one color because then you would have to go through the generated palette and try to fit your remaining colors into it.

This is exactly where the `generatePalette()` method shines!

You can provide an object with multiple color levels and it will handle the rest for you. The best thing about the `generatePalette()` method is that it will actually respect the colors you choose. It will adjust the palette to make sure all the colors you provided will fit into it seamlessly.

Once you generate the palettes, you can use them to create color themes for your app.

## Setting the default theme

By default, the "default" theme will be used as the default theme for your application. If for some reason, you want to have more than one themes and choose something other than the "default", you can do so by setting the default theme via `src/app.config.ts` file. You can also change the theme runtime using the `FuseConfigService`.

## Schemes

Every color theme you configure will automatically have 2 schemes; Light and Dark. This way you can immediately change to a "dark" mode without losing your theme or setting up a separate "dark" theme.

You can set the default scheme via `src/app.config.ts` file. You can also change the scheme runtime using the `FuseConfigService`.

While you can set the scheme to "light" or "dark" you can also set it to "auto". "auto" mode will automatically switch between the "light" and "dark" schemes depending on the user's operating system's setting.