Theme Service

Manages the application's visual theme — dark mode, base color, primary accent color, and border radius. Persists preferences to localStorage and applies them to the DOM via JS interop.

Programmatic Theme Control

Inject ThemeService to programmatically change theme settings. Subscribe to OnThemeChanged to re-render when the theme changes.

@inject ThemeService ThemeService

<BbButton OnClick="async () => await ThemeService.ToggleDarkModeAsync()">
    Toggle Dark Mode
</BbButton>

<BbButton OnClick="async () => await ThemeService.SetPrimaryColorAsync(PrimaryColor.Blue)">
    Blue Theme
</BbButton>

<BbButton OnClick="async () => await ThemeService.SetRadiusAsync(0.75)">
    Rounded Corners
</BbButton>

@code {
    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            ThemeService.OnThemeChanged += () => InvokeAsync(StateHasChanged);
            await ThemeService.InitializeAsync();
        }
    }
}

API Reference

Properties

Property	Type	Default	Description
IsDarkMode	bool	—	Whether dark mode is currently active.
BaseColor	BaseColor	Zinc	The current base (gray scale) color.
PrimaryColor	PrimaryColor	Default	The current primary accent color.
Radius	double	0.5	The current border radius in rem.
IsInitialized	bool	false	Whether the service has been initialized.

Events

Property	Type	Default	Description
OnThemeChanged	Action?	null	Raised after any theme property changes. Subscribe to trigger StateHasChanged.

Methods

Property	Type	Default	Description
InitializeAsync()	Task	—	Loads saved preferences from localStorage, detects system color scheme, and applies theme to DOM. Safe to call multiple times.
ToggleDarkModeAsync()	Task	—	Toggles between dark and light mode.
SetDarkModeAsync(bool)	Task	—	Sets dark mode to the specified value.
SetBaseColorAsync(BaseColor)	Task	—	Sets the base (gray scale) color palette.
SetPrimaryColorAsync(PrimaryColor)	Task	—	Sets the primary accent color.
SetRadiusAsync(double)	Task	—	Sets the border radius in rem (e.g., 0, 0.3, 0.5, 0.75, 1.0).

ThemeOptions

Configuration passed via configureTheme on AddBlazorBlueprintComponents().

Property	Type	Default	Description
DefaultBaseColor	BaseColor	Zinc	Default base color palette.
DefaultPrimaryColor	PrimaryColor	Default	Default primary accent color.
DefaultDarkMode	bool	false	Whether dark mode is enabled by default. Overridden by system preference when DetectSystemPreference is true.
DetectSystemPreference	bool	true	Detects the user's OS color scheme preference on first load.
DefaultRadius	double	0.5	Default border radius in rem.
PersistToLocalStorage	bool	true	Whether to persist theme preferences to localStorage.

Enums

BaseColor

The base (gray scale) color palette for backgrounds, borders, and neutral UI elements.

Value	Description
`Zinc`	Cool gray with a subtle blue undertone. Default for shadcn/ui.
`Slate`	Cool blue-gray, slightly warmer than Zinc.
`Gray`	Pure, balanced gray with no color tint.
`Neutral`	True neutral gray — identical lightness steps with zero chroma.
`Stone`	Warm gray with a slight yellow/brown undertone.

PrimaryColor

The primary accent color for buttons, links, focus rings, and interactive elements.

Value	Description
`Default`	Inherits from the base color palette (no override).
`Blue`	Blue primary.
`Violet`	Violet primary.
`Purple`	Purple primary.
`Rose`	Rose primary.
`Red`	Red primary.
`Orange`	Orange primary.
`Amber`	Amber primary.
`Yellow`	Yellow primary.
`Lime`	Lime primary.
`Green`	Green primary.
`Emerald`	Emerald primary.
`Teal`	Teal primary.
`Cyan`	Cyan primary.
`Sky`	Sky primary.
`Indigo`	Indigo primary.
`Fuchsia`	Fuchsia primary.
`Pink`	Pink primary.

View source on GitHub

Previous Keyboard Shortcut

Version v3 Documentation