BlazorThemes

https://github.com/zl23abdessamed/blazorthemes
Admin
BlazorThemes is a comprehensive theme management solution for Blazor applications, offering advanced...
Tokens:5,369
Snippets:37
Trust Score:5.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Configure Blazor Themes Provider

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Sets up the BlazorThemesProvider component with various options like theme transition, scheduling, and start times. It also includes routing for the application.

```razor
<BlazorThemesProvider 
    Options="@themeOptions"
    OnThemeChanged="HandleThemeChanged"
    EnableScheduling="true"
    LightStartTime="06:00"
    DarkStartTime="18:00"
    DefaultTransition="ThemeTransitionType.Fade"
    TransitionDuration="300ms"
    EnableCrossTabs="true">
    
    <!-- Your application content -->
    <Router AppAssembly="@typeof(App).Assembly">
        <RouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)" />
    </Router>
    
</BlazorThemesProvider>
```

--------------------------------

### Install BlazorThemes NuGet Package

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Installs the BlazorThemes package using the .NET CLI. This is the first step to integrating theme management into your Blazor application.

```bash
dotnet add package BlazorThemes
```

--------------------------------

### BlazorThemes Project Setup (Bash)

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

This bash script provides commands to set up the BlazorThemes project locally. It includes cloning the repository, navigating into the project directory, and restoring project dependencies using the .NET CLI. These steps are essential for developers to begin working with or contributing to the project.

```bash
# Clone the repository
git clone https://github.com/Zl23Abdessamed/BlazorThemes

# Navigate to project directory
cd BlazorThemes

# Restore dependencies
dotnet restore

```

--------------------------------

### BlazorThemes Nested Theming Example

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

Demonstrates how BlazorThemes supports nested theming by applying different data-theme attributes to nested HTML elements. This allows for localized theme overrides within the application.

```html
<div data-theme="dark">
  <!-- Uses dark theme -->
  <div data-theme="light">
    <!-- Uses light theme -->
  </div>
</div>
```

--------------------------------

### BlazorThemes Component Styling with Variables

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

Shows a Blazor Razor component example that utilizes CSS variables for its styling. It dynamically sets background and text colors based on --bg-card, --text-card, and --heading-color variables.

```razor
<div class="card" style="background: var(--bg-card); color: var(--text-card);">
    <h3 style="color: var(--heading-color);">@Title</h3>
    <p>@Content</p>
</div>
```

--------------------------------

### Blazor Theme-Aware Component Example

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

This Blazor component demonstrates how to use the BlazorThemesService to manage theme settings. It includes buttons for switching themes, applying transitions, and toggling between themes. It also displays the current state of the theme service, updating in real-time when themes change. Dependencies include the BlazorThemesService and MouseEventArgs for ripple effect positioning. The component handles theme changes by subscribing to the OnThemeChanged event and disposing of the subscription upon component disposal.

```razor
@page "/theme-demo"
@inject BlazorThemesService ThemesService

<div class="theme-demo-container">
    <h1>🎨 Theme Demo</h1>
    
    <!-- Theme Controls -->
    <div class="theme-controls">
        <h3>Basic Controls</h3>
        <button @onclick='() => SetTheme("light")' class="btn btn-light">
            ☀️ Light
        </button>
        <button @onclick='() => SetTheme("dark")' class="btn btn-dark">
            🌙 Dark
        </button>
        <button @onclick='() => SetTheme("auto")' class="btn btn-auto">
            🔄 Auto
        </button>
        <button @onclick="ToggleTheme" class="btn btn-toggle">
            ⚡ Toggle
        </button>
    </div>
    
    <!-- Transition Effects -->
    <div class="transition-controls">
        <h3>Transition Effects</h3>
        <button @onclick='() => SetThemeWithTransition("dark", "fade")'>
            🌅 Fade to Dark
        </button>
        <button @onclick='() => SetThemeWithTransition("light", "slide")'>
            ⬅️ Slide to Light
        </button>
        <button @onclick='(e) => SetThemeWithRipple("auto", e)'>
            💫 Ripple Effect
        </button>
    </div>
    
    <!-- Theme Information -->
    <div class="theme-info">
        <h3>Current Theme State</h3>
        <ul>
            <li><strong>Selected:</strong> @currentState?.Theme</li>
            <li><strong>Applied:</strong> @currentState?.ResolvedTheme</li>
            <li><strong>System:</strong> @currentState?.SystemTheme</li>
            <li><strong>Transitioning:</strong> @currentState?.IsTransitioning</li>
            <li><strong>Last Changed:</strong> @currentState?.LastChanged.ToString("HH:mm:ss")</li>
        </ul>
    </div>
</div>

@code {
    private ThemeState? currentState;
    
    protected override async Task OnInitializedAsync()
    {
        currentState = ThemesService.State;
        ThemesService.OnThemeChanged += HandleThemeChanged;
    }
    
    private async Task SetTheme(string theme)
    {
        await ThemesService.SetThemeAsync(theme);
    }
    
    private async Task ToggleTheme()
    {
        await ThemesService.ToggleThemeAsync();
    }
    
    private async Task SetThemeWithTransition(string theme, string transition)
    {
        await ThemesService.SetThemeWithTransitionAsync(theme, transition);
    }
    
    private async Task SetThemeWithRipple(string theme, MouseEventArgs e)
    {
        await ThemesService.SetThemeWithRippleAsync(theme, e.ClientX, e.ClientY);
    }
    
    private void HandleThemeChanged(ThemeState state)
    {
        currentState = state;
        InvokeAsync(StateHasChanged);
    }
    
    public void Dispose()
    {
        ThemesService.OnThemeChanged -= HandleThemeChanged;
    }
}
```

--------------------------------

### Configure BlazorThemes Services in Program.cs

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Adds BlazorThemes services to the application's service collection. Configures initial theme options, including available themes, system integration, and default transition type.

```csharp
builder.Services.AddBlazorThemes(options => {
    options.Themes = new[] { "light", "dark", "auto" };
    options.EnableSystem = true;
    options.TransitionType = "fade";
});
```

--------------------------------

### BlazorThemesService Methods

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

This section details the available methods for interacting with the BlazorThemesService to manage themes, transitions, and scheduling.

```APIDOC
## BlazorThemesService Methods

### Description
Methods for managing themes, scheduling, and transitions within the BlazorThemes library.

### Methods
- `SetThemeAsync(theme, options?): Promise<void>`
- `ToggleThemeAsync(options?): Promise<void>`
- `AddCustomThemeAsync(name, config): Promise<void>`
- `RemoveCustomThemeAsync(name): Promise<void>`
- `SetThemeWithTransitionAsync(theme, type): Promise<void>`
- `SetThemeWithRippleAsync(theme, x, y): Promise<void>`
- `CycleThemesAsync(options?): Promise<void>`
- `EnableSchedulingAsync(enable): Promise<void>`
- `SetScheduleAsync(lightStart, darkStart): Promise<void>`
- `ForceThemeAsync(theme): Promise<void>`
- `ClearForcedThemeAsync(): Promise<void>`
- `RefreshSystemThemeAsync(): Promise<void>`
- `GetThemeVariablesAsync(theme): Promise<Record<string, string>>`

### Parameters
#### SetThemeAsync
- **theme** (string) - Required - The name of the theme to set.
- **options** (object) - Optional - Transition options.

#### ToggleThemeAsync
- **options** (object) - Optional - Transition options.

#### AddCustomThemeAsync
- **name** (string) - Required - The name for the custom theme.
- **config** (object) - Required - An object containing CSS variables for the theme.

#### RemoveCustomThemeAsync
- **name** (string) - Required - The name of the custom theme to remove.

#### SetThemeWithTransitionAsync
- **theme** (string) - Required - The name of the theme to set.
- **type** (ThemeTransitionType) - Required - The type of transition to use.

#### SetThemeWithRippleAsync
- **theme** (string) - Required - The name of the theme to set.
- **x** (number) - Required - The x-coordinate of the ripple origin.
- **y** (number) - Required - The y-coordinate of the ripple origin.

#### CycleThemesAsync
- **options** (object) - Optional - Options for cycling themes.

#### EnableSchedulingAsync
- **enable** (boolean) - Required - Whether to enable or disable scheduling.

#### SetScheduleAsync
- **lightStart** (string) - Required - The start time for the light theme (e.g., '06:00').
- **darkStart** (string) - Required - The start time for the dark theme (e.g., '18:00').

#### ForceThemeAsync
- **theme** (string) - Required - The theme to force.

#### GetThemeVariablesAsync
- **theme** (string) - Required - The name of the theme to retrieve variables for.

### Response
#### Success Response (200)
- **void** - The operation was successful.
- **Record<string, string>** - For `GetThemeVariablesAsync`, an object containing theme variables.

### Request Example
```csharp
await BlazorThemesService.SetThemeAsync("dark");
await BlazorThemesService.ToggleThemeAsync();
await BlazorThemesService.AddCustomThemeAsync("myTheme", new { --bg-primary = "#111", --text-primary = "#fff" });
```
```

--------------------------------

### Apply Theme Transitions

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Demonstrates how to apply different visual transitions (Fade, Slide, Ripple, Blur) when switching themes using the ThemesService. This enhances the user experience with visual effects.

```csharp
// Fade transition (smooth and elegant)
await ThemesService.SetThemeWithTransitionAsync("dark", ThemeTransitionType.Fade);

// Slide transition (dynamic movement)
await ThemesService.SetThemeWithTransitionAsync("light", ThemeTransitionType.Slide);

// Ripple transition at click position (interactive)
await ThemesService.SetThemeWithRippleAsync("light", e.ClientX, e.ClientY);

// Blur transition (modern effect)
await ThemesService.SetThemeWithTransitionAsync("auto", ThemeTransitionType.Blur);
```

--------------------------------

### Blazor Theme Demo Component Implementation

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

This Razor component demonstrates how to use the BlazorThemesService to manage theme switching, transitions, and display current theme state. It includes buttons for basic theme control, transition effects, and displays detailed theme information. The component subscribes to theme changes and updates its state accordingly.

```razor
@page "/theme-demo"
@inject BlazorThemesService ThemesService

<div class="theme-demo-container">
    <h1>🎨 Theme Demo</h1>
    
    <!-- Theme Controls -->
    <div class="theme-controls">
        <h3>Basic Controls</h3>
        <button @onclick='() => SetTheme("light")' class="btn btn-light">
            ☀️ Light
        </button>
        <button @onclick='() => SetTheme("dark")' class="btn btn-dark">
            🌙 Dark
        </button>
        <button @onclick='() => SetTheme("auto")' class="btn btn-auto">
            🔄 Auto
        </button>
        <button @onclick="ToggleTheme" class="btn btn-toggle">
            ⚡ Toggle
        </button>
    </div>
    
    <!-- Transition Effects -->
    <div class="transition-controls">
        <h3>Transition Effects</h3>
        <button @onclick='() => SetThemeWithTransition("dark", "fade")'>
            🌅 Fade to Dark
        </button>
        <button @onclick='() => SetThemeWithTransition("light", "slide")'>
            ⬅️ Slide to Light
        </button>
        <button @onclick='(e) => SetThemeWithRipple("auto", e)'>
            💫 Ripple Effect
        </button>
    </div>
    
    <!-- Theme Information -->
    <div class="theme-info">
        <h3>Current Theme State</h3>
        <ul>
            <li><strong>Selected:</strong> @currentState?.Theme</li>
            <li><strong>Applied:</strong> @currentState?.ResolvedTheme</li>
            <li><strong>System:</strong> @currentState?.SystemTheme</li>
            <li><strong>Transitioning:</strong> @currentState?.IsTransitioning</li>
            <li><strong>Last Changed:</strong> @currentState?.LastChanged.ToString("HH:mm:ss")</li>
        </ul>
    </div>
</div>

@code {
    private ThemeState? currentState;
    
    protected override async Task OnInitializedAsync()
    {
        currentState = ThemesService.State;
        ThemesService.OnThemeChanged += HandleThemeChanged;
    }
    
    private async Task SetTheme(string theme)
    {
        await ThemesService.SetThemeAsync(theme);
    }
    
    private async Task ToggleTheme()
    {
        await ThemesService.ToggleThemeAsync();
    }
    
    private async Task SetThemeWithTransition(string theme, string transition)
    {
        await ThemesService.SetThemeWithTransitionAsync(theme, transition);
    }
    
    private async Task SetThemeWithRipple(string theme, MouseEventArgs e)
    {
        await ThemesService.SetThemeWithRippleAsync(theme, e.ClientX, e.ClientY);
    }
    
    private void HandleThemeChanged(ThemeState state)
    {
        currentState = state;
        InvokeAsync(StateHasChanged);
    }
    
    public void Dispose()
    {
        ThemesService.OnThemeChanged -= HandleThemeChanged;
    }
}

```

--------------------------------

### Configuration Options

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Details the configuration options available for customizing the Blazor Themes behavior.

```APIDOC
## Configuration Options

### Description
Defines the configurable settings for the Blazor Themes provider, allowing customization of themes, transitions, and other behaviors.

### Options
- **Themes** (string[]): Available themes (default: `["light", "dark", "auto"]`).
- **DefaultTheme** (string): Default theme on first load (default: `"light"`).
- **EnableSystem** (bool): Respect OS theme preferences (default: `true`).
- **TransitionType** (string): Default transition effect (default: `"fade"`).
- **TransitionDuration** (string): Transition duration (default: `"300ms"`).
- **EnableCrossTabs** (bool): Sync themes across browser tabs (default: `true`).
- **StorageKey** (string): LocalStorage key (default: `"blazor-themes"`).
- **EnableScheduling** (bool): Enable time-based scheduling (default: `false`).
- **ScheduleConfig** (ScheduleConfig): Scheduling configuration.
```

--------------------------------

### Quick Theme Toggle using ThemesService

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Implements a button to quickly toggle between the current theme and the next available theme using the ThemesService.ToggleThemeAsync method.

```razor
<button @onclick="ThemesService.ToggleThemeAsync" 
        class="btn btn-toggle">
    🔄 Toggle Theme
</button>
```

--------------------------------

### BlazorThemesService Methods

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

This section details the available methods for interacting with the BlazorThemesService to control theme behavior.

```APIDOC
## BlazorThemesService Methods

### Description
Provides methods to dynamically manage and manipulate themes within your Blazor application.

### Methods
- **SetThemeAsync**: Set theme with optional transition effects.
- **ToggleThemeAsync**: Toggle between light/dark themes.
- **AddCustomThemeAsync**: Add custom theme with CSS variables.
- **RemoveCustomThemeAsync**: Remove a custom theme.
- **SetThemeWithTransitionAsync**: Change theme with specific transition.
- **SetThemeWithRippleAsync**: Change theme with ripple effect.
- **CycleThemesAsync**: Cycle through available themes.
- **EnableSchedulingAsync**: Enable/disable time-based scheduling.
- **SetScheduleAsync**: Configure schedule times.
- **ForceThemeAsync**: Force a specific theme.
- **ClearForcedThemeAsync**: Clear forced theme.
- **RefreshSystemThemeAsync**: Refresh system theme detection.
- **GetThemeVariablesAsync**: Get CSS variables for a theme.
```

--------------------------------

### Set Themes using ThemesService

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Provides buttons to switch between predefined themes (light, dark, auto) using the ThemesService. Each button calls SetThemeAsync with the corresponding theme name.

```razor
<div class="theme-controls">
    <button @onclick='() => ThemesService.SetThemeAsync("light")' 
            class="btn btn-light">
        ☀️ Light
    </button>
    
    <button @onclick='() => ThemesService.SetThemeAsync("dark")' 
            class="btn btn-dark">
        🌙 Dark
    </button>
    
    <button @onclick='() => ThemesService.SetThemeAsync("auto")' 
            class="btn btn-auto">
        🔄 Auto
    </button>
</div>
```

--------------------------------

### Configure Theme Scheduling

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Enables and configures automatic theme switching based on time of day. It includes options for basic scheduling and advanced settings for different weekday and weekend times.

```csharp
// Enable automatic scheduling
await ThemesService.EnableSchedulingAsync(true);

// Set custom schedule (light theme starts at 6 AM, dark at 6 PM)
await ThemesService.SetScheduleAsync("06:00", "18:00");

// Advanced scheduling with different weekday/weekend times
await ThemesService.SetAdvancedScheduleAsync(
    weekdayLight: "07:00", 
    weekdayDark: "19:00",
    weekendLight: "08:00", 
    weekendDark: "20:00"
);
```

--------------------------------

### Provide Theme Services via Cascading Values

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Demonstrates how to use CascadingValue components to make BlazorThemesService, its state, and configuration available throughout the component tree.

```razor
<CascadingValue Value="BlazorThemesService" Name="BlazorThemesService">
    <CascadingValue Value="@BlazorThemesService.State" Name="ThemeState">
        <CascadingValue Value="@BlazorThemesService.Config" Name="ThemeConfig">
            <!-- Your app content with full theme context -->
            @Body
        </CascadingValue>
    </CascadingValue>
</CascadingValue>
```

--------------------------------

### ThemeState Properties

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

This section outlines the properties available in the ThemeState object, providing information about the current theme, system theme, and scheduling status.

```APIDOC
## ThemeState Properties

### Description
Properties reflecting the current state of theming, including selected theme, system theme, and scheduling status.

### Properties
- **Theme** (string): The currently selected theme name.
- **ResolvedTheme** (string): The actual applied theme, resolving 'auto' to the system theme if applicable.
- **SystemTheme** (string): The current theme detected from the operating system.
- **Themes** (string[]): An array of available built-in theme names.
- **CustomThemes** (string[]): An array of names for custom themes that have been added.
- **ForcedTheme** (string?): The name of the currently forced theme, or null if no theme is forced.
- **IsTransitioning** (bool): Indicates whether a theme transition is currently in progress.
- **SchedulingEnabled** (bool): A boolean value indicating if time-based theme scheduling is enabled.
- **ScheduleConfig** (ScheduleConfig): An object containing the current schedule configuration (start times for light and dark themes).
- **LastChanged** (DateTime): The date and time when the theme was last changed.
- **TransitionDuration** (TimeSpan): The duration of the current theme transition in milliseconds.

### Response
#### Success Response (200)
- **ThemeState object** - An object containing the current theming state properties.

### Example
```csharp
string currentTheme = ThemeState.Theme;
bool scheduling = ThemeState.SchedulingEnabled;
```
```

--------------------------------

### Add Custom Theme with CSS Properties

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Adds a custom theme named 'midnight' with specific CSS properties like primary color, background color, and border-radius. This allows for deep customization beyond predefined themes.

```csharp
var customThemeConfig = new Dictionary<string, string>
{
    ["primary-color"] = "#ff6b6b",
    ["secondary-color"] = "#4ecdc4", 
    ["background-color"] = "#f8f9fa",
    ["text-color"] = "#2d3748",
    ["border-radius"] = "8px",
    ["shadow-color"] = "rgba(0, 0, 0, 0.1)"
};

await ThemesService.AddCustomThemeAsync("midnight", customThemeConfig);
```

--------------------------------

### BlazorThemes Custom Theme Definition

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

Illustrates how to define a new custom theme, such as 'midnight', by adding specific CSS variables within a data-theme attribute selector. This allows for easy extension of available themes.

```css
[data-theme="midnight"] {
    --bg-primary: #121826;
    --text-primary: #e0e7ff;
    --accent-primary: #7e22ce;
    /* ... */
}
```

--------------------------------

### BlazorThemes CSS Styling with Variables

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/BlazorThemes/README.md

Defines CSS variables for light and dark themes using attribute selectors. Also shows how component styles consume these variables for dynamic theming. This approach ensures separation of concerns and performance.

```css
[data-theme="light"] {
    --bg-primary: #ffffff;
    --bg-secondary: #f8fafc;
    --text-primary: #1e293b;
    --accent-primary: #3b82f6;
    /* ...other variables */
}

[data-theme="dark"] {
    --bg-primary: #0f172a;
    --bg-secondary: #1e293b;
    --text-primary: #f1f5f9;
    --accent-primary: #60a5fa;
    /* ...other variables */
}

/* Component styling using variables */
.component {
    background-color: var(--bg-primary);
    color: var(--text-primary);
    border: 1px solid var(--border-primary);
}

.button {
    background-color: var(--accent-primary);
    color: var(--text-on-accent);
}
```

--------------------------------

### ThemeState Properties

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Exposes properties to access the current state of the Blazor Themes service.

```APIDOC
## ThemeState Properties

### Description
Provides access to the current theme state, including selected theme, available themes, and transition status.

### Properties
- **Theme** (string): Currently selected theme.
- **ResolvedTheme** (string): Actual applied theme (resolves 'auto').
- **SystemTheme** (string): Current operating system theme.
- **Themes** (string[]): Available built-in themes.
- **CustomThemes** (string[]): Available custom theme names.
- **ForcedTheme** (string?): Currently forced theme.
- **IsTransitioning** (bool): Whether a transition is in progress.
- **SchedulingEnabled** (bool): Whether scheduling is active.
- **ScheduleConfig** (ScheduleConfig): Current scheduling configuration.
- **LastChanged** (DateTime): When theme was last changed.
- **TransitionDuration** (TimeSpan): Current transition duration.
```

--------------------------------

### Add BlazorThemesProvider to Root Component

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Wraps the application's root routing component with BlazorThemesProvider to enable theme management across the application. This component is essential for theme functionality.

```razor
<BlazorThemesProvider>
    <Router AppAssembly="@typeof(App).Assembly">
        <!-- Your app content -->
    </Router>
</BlazorThemesProvider>
```

--------------------------------

### Force or Clear Theme

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Provides methods to temporarily override user theme preferences with a specific theme ('dark', 'midnight') or to revert to the user's preference by clearing the forced theme.

```csharp
// Force dark theme (useful for presentations, demos)
await ThemesService.ForceThemeAsync("dark");

// Force custom theme for special events
await ThemesService.ForceThemeAsync("midnight");

// Clear forced theme and return to user preference
await ThemesService.ClearForcedThemeAsync();
```

--------------------------------

### Accessing Current Theme State

Source: https://github.com/zl23abdessamed/blazorthemes/blob/master/README.md

Conditionally renders content based on the resolved theme state. It checks if the current theme is 'dark' and displays different content accordingly.

```razor
@if (currentState?.ResolvedTheme == "dark") 
{
    <div class="dark-mode-content">
        <h3>🌙 Dark Mode Active</h3>
        <p>This content is optimized for dark theme.</p>
    </div>
}
else 
{
    <div class="light-mode-content">
        <h3>☀️ Light Mode Active</h3>
        <p>This content is optimized for light theme.</p>
    </div>
}
```
Tokens:
Raw