Overview
A theme is a collection of design elements, including colors, typography, and component styles, that defines the visual appearance of a UI. It provides a consistent look and feel across all components, allowing developers to easily customize and align the UI with the app's brand identity or design preferences. By applying a theme, you can ensure uniformity in the presentation.
Theming in LumexUI
In LumexUI, theming is designed with Blazor developers in mind, offering a flexible and powerful approach to UI customization.
The theming system consists of two key parts: a C# object and a Tailwind CSS configuration, which together provide full control over your UI's design.
C# Object for Customization
LumexUI exports the
LumexThemethat allows you to configure colors, fonts, layout settings, and more. This approach ensures that Blazor developers can define their theme programmatically, staying within the familiar environment. By using this model, you can easily specify global design variables, making your application highly customizable while keeping your theming logic within your Blazor code.Extensible Tailwind CSS Configuration
In addition to the C# object, LumexUI leverages Tailwind CSS for styling. The Tailwind CSS configuration is fully extensible, allowing you to build upon the base configurations set by the library. Developers can extend the default Tailwind setup to suit their specific needs, adding or modifying utility classes for more granular control over the design.
Learn MoreCustom Tailwind CSS Plugin
To ensure seamless integration between the
Learn MoreLumexThemeconfigurations and Tailwind CSS, LumexUI exports a custom Tailwind plugin. This plugin takes the configurations defined in C# and injects them into the Tailwind config, automatically extending it with your custom styles and settings. This means that any C# theme adjustments you make will be reflected in your Tailwind styles, creating a smooth and cohesive theming experience for Blazor applications.
Setup
The first step to using LumexUI's theming capabilities is adding
the LumexThemeProvider component to your MainLayout.razor file.
<LumexThemeProvider />
The following section assumes that you have already completed a basic setup of Tailwind CSS. If you haven't, please refer to the official documentation to complete the setup before proceeding.
The last step is adding the LumexUI plugin to your tailwind.config.js file.
const lumexui = require("{PATH_TO_NUGET}/theme/plugin");
/** @type {import("tailwindcss").Config} */
module.exports = {
content: [
// ...
"{PATH_TO_NUGET}/theme/components/*.cs"
],
theme: {
extend: {},
},
plugins: [lumexui],
};
Usage
After setup, the default theme will be automatically utilized. However, if you would like to customize it, you can either override the defaults or create a completely new one.
public record MyTheme : LumexTheme
{
public MyTheme()
{
DefaultTheme = ThemeType.Light;
Light = new ThemeConfigLight()
{
Layout = new LayoutConfig() { /* ... */ },
Colors = new ThemeColorsLight() { /* ... */ },
};
Dark = new ThemeConfigDark()
{
Layout = new LayoutConfig() { /* ... */ },
Colors = new ThemeColorsDark() { /* ... */ },
};
}
}
Then, pass it as the Theme parameter into the LumexThemeProvider.
<LumexThemeProvider Theme="new MyTheme()" />
Types
LumexTheme
/// <summary>
/// Represents the configuration settings for themes.
/// </summary>
public record LumexTheme
{
public ThemeConfigLight Light { get; set; }
public ThemeConfigDark Dark { get; set; }
public ThemeType DefaultTheme { get; set; }
}
ThemeConfig
/// <summary>
/// Represents the configuration settings for a theme.
/// </summary>
public abstract record ThemeConfig<TColors> where TColors : ThemeColors
{
public TColors Colors { get; init; }
public LayoutConfig Layout { get; init; }
}
/// <summary>
/// Represents the default configuration settings for a light theme.
/// </summary>
public record ThemeConfigLight : ThemeConfig<ThemeColorsLight> { /* ... */ }
/// <summary>
/// Represents the default configuration settings for a dark theme.
/// </summary>
public record ThemeConfigDark : ThemeConfig<ThemeColorsDark> { /* ... */ }
LayoutConfig
/// <summary>
/// Represents a base size scale.
/// </summary>
public record BaseScale
{
public string? Sm { get; set; }
public string? Md { get; set; }
public string? Lg { get; set; }
}
/// <summary>
/// Represents a font scale.
/// </summary>
public record FontScale : BaseScale
{
public string? Xs { get; set; }
}
/// <summary>
/// Represents the font family settings.
/// </summary>
public record FontFamily
{
public string? Sans { get; set; }
public string? Mono { get; set; }
}
/// <summary>
/// Represents the layout settings for a theme.
/// </summary>
public record LayoutConfig
{
public FontScale FontSize { get; set; }
public FontScale LineHeight { get; set; }
public FontFamily? FontFamily { get; set; }
public BaseScale Radius { get; set; }
public BaseScale Shadow { get; set; }
public double DisabledOpacity { get; set; }
public double FocusOpacity { get; set; }
public double HoverOpacity { get; set; }
public double DividerOpacity { get; set; }
}
ThemeColors
/// <summary>
/// Represents a set of base colors used in a theme.
/// </summary>
public record BaseColors
{
public ColorScale Background { get; set; }
public ColorScale Foreground { get; set; }
public ColorScale Overlay { get; set; }
public ColorScale Divider { get; set; }
public ColorScale Focus { get; set; }
public ColorScale Content1 { get; set; }
public ColorScale Content2 { get; set; }
public ColorScale Content3 { get; set; }
}
/// <summary>
/// Represents a set of theme colors.
/// </summary>
public record ThemeColors : BaseColors
{
public ColorScale Default { get; set; }
public ColorScale Primary { get; set; }
public ColorScale Secondary { get; set; }
public ColorScale Success { get; set; }
public ColorScale Warning { get; set; }
public ColorScale Danger { get; set; }
public ColorScale Info { get; set; }
}
/// <summary>
/// Represents a set of light theme default colors.
/// </summary>
public record ThemeColorsLight : ThemeColors { /* ... */ }
/// <summary>
/// Represents a set of dark theme default colors.
/// </summary>
public record ThemeColorsDark : ThemeColors { /* ... */ }