Theming - bit BlazorUI

In bit BlazorUI, you can customize the look and feel of your app using the theme features by specifying the color of the components, the darkness of the surfaces, the level of shadow, the appropriate opacity of elements, etc.

Different aspects of the UI element styles are pre-defined in CSS variables that let you apply a consistent tone to your app. It allows you to customize all design aspects of your project to meet the specific needs of your business or brand.

The default theme is based on the Microsoft Fluent design system with light and dark theme types available to choose from. By default, components use the light theme type.

Quick setup

To get started with bit BlazorUI Theme as fast as possible, you can try the system theme feature of it.
First you need to register the bit BlazorUI services as follows:

builder.Services.AddBitBlazorUIServices();

And then add a specific attribute named use-system-theme to the html tag:

<html use-system-theme>...</html>

Now with this setup, the app will follow the system theme (dark or light) automatically.

CSS variables

All CSS variables defined in the Theme system of the bit BlazorUI are attached to the root element like this:

:root,
:root[bit-theme="light"],
:root[bit-theme="fluent"],
:root[bit-theme="fluent-light"] {

...

    --bit-clr-pri: #1A86D8;
    --bit-clr-pri-hover: #197FCD;
    --bit-clr-pri-active: #1779C2;
    --bit-clr-pri-dark: #096FBD;
    --bit-clr-pri-dark-hover: #0969B4;
    --bit-clr-pri-dark-active: #0864AA;
    --bit-clr-pri-light: #A3CFEF;
    --bit-clr-pri-light-hover: #8CC3EC;
    --bit-clr-pri-light-active: #76B6E8;
    --bit-clr-pri-text: #FFF;

...

}

The source code of these CSS variables is available in the bit BlazorUI GitHub repo .
You can simply override these values to customize the UI.

Note: If you're using scss in your project, you can use bit-css-variables.scss file which introduces scss variables for each bit theme css variable. you can find the latest version of this file here .

ThemeManager

In bit BlazorUI the BitThemeManager class is available to customize the Theme.
To start using the BitThemeManager, you first need to register bit BlazorUI services like this:

builder.Services.AddBitBlazorUIServices();

Now you can call methods of an injected instance of the BitThemeManager class to customize the UI:

[Inject] private BitThemeManager _bitThemeManager { get; set; }

For example using ApplyBitThemeAsync method and an instance of the BitTheme class, which contains the desired theme values, you can change the current theme styles.
The ApplyBitThemeAsync method accepts two parameters: a BitTheme instace and an optional target element which is by default the body element.
Here's an example of how to apply custom theme values to the entire body:

var myTheme = new BitTheme();
myTheme.Color.Foreground.Primary = "#111";
myTheme.Color.Background.Primary = "#777";
_bitThemeManager.ApplyBitThemeAsync(myTheme);

You can set the current theme using the SetThemeAsync method:

await _bitThemeManager.SetThemeAsync("fluent-dark");

You can also toggle current theme between dark/light using the ToggleDarkLightAsync method:

await _bitThemeManager.ToggleDarkLightAsync();

This method returns the name of the new toggled theme.
The BitThemeManager has a method named GetCurrentThemeAsync which returns the name of the current theme:

var currentTheme = await _bitThemeManager.GetCurrentThemeAsync();

System Theme

In bit BlazorUI you can use the system theme as the default theme when the app starts up.
In order to enable this feature a specific attribute named use-system-theme should be added to the html tag:

<html use-system-theme>...</html>

CSS in C#

In bit BlazorUI the BitCss class is available to access theme related CSS classes & variables in C#.
You can use different properties of this class to further customize your UI:

<html>
    <head>...</head>
    <body class="@BitCss.Class.Color.Background.Primary @BitCss.Class.Color.Foreground.Primary">
        ...
    </body>
</html>

This class contians two main property for accessing CSS classes (BitCss.Class) and CSS variables (BitCss.Var).

<div style="border-color:var(@BitCss.Var.Color.Border.Secondary)">
    hello world!
</div>

ThemeProvider

In bit BlazorUI the BitThemeProvider component is available to further customize the Theme.
You can wrap any elements with the BitThemeProvider component and assign an instance of BitTheme to it:

<BitThemeProvider Theme="myTheme">
    <BitCheckbox Label="Check me!" />
</BitThemeProvider>

@code {
    BitTheme myTheme = new()
    {
        Color = { Primary = { Main = "red" } }
    };
}

The applied theme provided by the BitThemeProvider can be accessed directly using a CascadingParameter in the child components:

[CascadingParameter] public BitTheme? Theme { get; set; }

You can also nest BitThemeProvider components to achieve the desired style:

<BitThemeProvider Theme="myTheme">
    <BitCheckbox Label="Check me!" />
    <BitThemeProvider Theme="myTheme2">
        <BitCheckbox Label="Check me 2!" />
    </BitThemeProvider>
</BitThemeProvider>

@code {
    BitTheme myTheme = new()
    {
        Color = { Primary = { Main = "red" } }
    };

    BitTheme myTheme2 = new()
    {
        Color = { Primary = { Main = "blue" } }
    };
}

JavaScript API

bit BlazorUI also has a JavaScript API through BitTheme javascript object to customize the UI of the app even further.
The differnet functions available in this object are as follows:

BitTheme.get()

Gets the current theme.

BitTheme.set('dark')

Sets the current theme.

BitTheme.toggleDarkLight()

Toggles the current theme between dark & light.

BitTheme.useSystem()

Uses the current theme of the system (dark or light) as the app theme.

BitTheme.onChange((newTheme, oldTheme) => {
    if (newTheme.includes('dark')) {
        document.body.classList.add('bit-theme-dark');
        document.body.classList.remove('bit-theme-light');
    } else {
        document.body.classList.add('bit-theme-light');
        document.body.classList.remove('bit-theme-dark');
    }
});

An event that fires when the current theme changes.

BitTheme.applyBitTheme({...}, el)

Applies an instance of BitTheme to the specified or body element just like the ApplyBitThemeAsync method of the BitThemeManager.

BitTheme.isSystemDark()

Checks if the current theme of the system is dark.

BitTheme.init({
    system: true,
    onChange: (newTheme: string, oldThem: string) => {
        if (newTheme === 'dark') {
            document.body.classList.add('bit-theme-dark');
            document.body.classList.remove('bit-theme-light');
        } else {
            document.body.classList.add('bit-theme-light');
            document.body.classList.remove('bit-theme-dark');
        }
    }
});

Initializes the BitTheme object using the provided options.