Home Docs

Theming


Using 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

bit-theme-system
to the
html
tag: 


<html bit-theme-system>...</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 like what we did in our main website (bitplatform.dev) in this file : 


// overridden values:

:root[bit-theme="dark"] {
    --bit-clr-sec: transparent;
    --bit-clr-sec-hover: #061342;
    --bit-clr-bg-pri: #060E2D;
    --bit-clr-bg-sec: #0a153d;
    --bit-clr-bg-pri-hover: #07154a;
    --bit-clr-bg-pri-active: #061241;
    --bit-clr-bg-sec-hover: #07154a;
    --bit-clr-fg-sec: #dddddd;
}

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


Using 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

bit-theme-system
should be added to the
html
tag: 


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

Persist Theme


Using bit BlazorUI, you can persist the current theme in the local storage.
To enable this feature a specific attribute named

bit-theme-persist
should be added to the
html
tag: 


<html bit-theme-persist>...</html>

Default Theme


Using bit BlazorUI, you can change the default theme which is

light
using a specific attribute named
bit-theme-default
on the
html
tag: 


<html bit-theme-default="dark">...</html>

Customizing theme names


In bit BlazorUI, the default name of the available themes are

light
and
dark
. you can change these default names using the following attributes on the
html
tag: 


<html bit-theme-dark="custom-dark" bit-theme-light="custom-light">...</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 has a rather extensive 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:



get: gets the current theme. 

const currentTheme = BitTheme.get();


set: sets the current theme. 

BitTheme.set('dark');


toggleDarkLight: toggles the current theme between dark & light. 

BitTheme.toggleDarkLight();


useSystem: uses the current theme of the system (dark or light) as the app theme. 

BitTheme.useSystem();


onChange: an event that fires when the current theme changes. 

BitTheme.onChange((newTheme, oldTheme) => {
    if (newTheme.includes('dark')) {
        document.querySelector("meta[name=theme-color]")!.setAttribute('content', '#0d1117');
    } else {
        document.querySelector("meta[name=theme-color]")!.setAttribute('content', '#ffffff');
    }
});


applyBitTheme: applies an instance of BitTheme to the specified element or the body element, just like the

ApplyBitThemeAsync
method of the
BitThemeManager
. 

BitTheme.applyBitTheme({ '--bit-clr-pri': '#1A86D8' }, myElement)


isSystemDark: checks if the current theme of the system is dark. 

BitTheme.isSystemDark();


init: initializes the BitTheme object using the provided options. 

BitTheme.init({
    system: true,
    persist: true,
    theme: 'custom-dark',
    default: 'custom-dark',
    darkTheme: 'custom-dark',
    lightTheme: 'custom-light',
    onChange: (newTheme: string, oldTheme: string) => {
        if (newTheme === 'custom-dark') {
            document.querySelector("meta[name=theme-color]")!.setAttribute('content', '#0d1117');
        } else {
            document.querySelector("meta[name=theme-color]")!.setAttribute('content', '#ffffff');
        }
    }
});

Feedback


You can give us your feedback through our GitHub repo by filing a new Issue or starting a new Discussion.


Or you can review / edit this page on GitHub.