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();

Precedence

SetThemeAsync
updates the
bit-theme
attribute on the document root so the packaged Fluent stylesheets supply the base token values.
ApplyBitThemeAsync
writes CSS variables onto an element (default:
body
), which overrides those tokens for the subtree because inline styles win over stylesheet rules for the same property. Use a named preset (see
BitThemePresets
) with
SetThemeAsync
, then call
ApplyBitThemeAsync
with a partial
BitTheme
for runtime brand tweaks.


Presets, utilities, SSR

BitThemePresets
exposes well-known
bit-theme
names (for example
BitThemePresets.FluentDark
).
BitThemeUtilities.ToCssVariables
maps a
BitTheme
to a dictionary of CSS custom properties;
BitThemeUtilities.Merge
merges a child theme over a parent (same rules as
BitThemeProvider
).
BitThemeSerialization
serializes or deserializes a theme as JSON for storage.
BitThemeColorDerivation.FillColorRoleFromMain
can fill unset steps on
BitThemeColorVariants
from a single main hex color.
Bit.BlazorUI.Extras
reuses the same design tokens (for example
$clr-pri
in SCSS) so preset and
BitTheme
overrides apply consistently. For an optional early
head
script that reduces theme flash with persistence, see the
BitThemeSsr
section below. 


await _bitThemeManager.SetThemeAsync(BitThemePresets.FluentDark);

var json = BitThemeSerialization.Serialize(myTheme);
var copy = BitThemeSerialization.Deserialize(json);

BitThemeColorDerivation.FillColorRoleFromMain(myTheme.Color.Primary, "#1A86D8");

BitThemeSsr


BitThemeSsr
helps reduce the wrong-theme flash on first paint when you use
bit-theme-persist
(and optional
bit-theme
,
bit-theme-default
,
bit-theme-light
,
bit-theme-dark
on
<html>
). It injects a tiny script at the very start of
<head>
so
bit-theme
is restored from
localStorage
(when persist is enabled) or resolved for
system
before your Fluent stylesheets run.


Place it at the start of

<head>
, before bit BlazorUI / Fluent CSS links, so selectors such as
:root[bit-theme="…"]
match immediately.


In a Blazor Web App root document (for example

Components/App.razor
), emit the full script tag:


<head>
    @((MarkupString)@BitThemeSsr.InlineHeadScript)
    @* stylesheet links after this *@
</head>

If you prefer your own

<script>
wrapper, use only the JavaScript body:


<script>@BitThemeSsr.InlineHeadScriptBody</script>

Behavior matches the client

BitTheme
script: with
bit-theme-persist
, the stored key
bit-current-theme
is read; if the value is
system
,
prefers-color-scheme
picks the light or dark name from
bit-theme-light
/
bit-theme-dark
(defaulting to
light
and
dark
when those attributes are omitted).


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.Main @BitCss.Class.Color.Foreground.Primary.Main">
        ...
    </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.Main)">
    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.