Themes Overview
Telerik UI for Blazor comes with a set of built-in CSS themes that control the visual appearance of the components. Each theme determines the components' colors, borders, backgrounds, size, layout, position, font size and sometimes the font family.
In This Article
- Definitions for theme and swatch and how the themes relate to the components
- All built-in theme and swatch names and how to preview them
- How to register a theme in your app
- How to ensure compatibility between the Telerik components and the theme version
Basics
Theme
A theme is a collection of styles in a CSS file, which determine the appearance of the Telerik Blazor components, including fonts, colors, sizes and layouts. For example, Default and Bootstrap are two built-in theme names.
Swatch
A theme swatch is a color variation of a theme. All swatches of a given theme> use the same fonts, sizes, and layouts. On the other hand, the text colors, background colors and border colors are different. For example, Default Ocean Blue and Bootstrap Nordic are two built-in swatch names.
When the Telerik UI for Blazor documentation talks about a given theme name, for example Default, this implies the Main swatch of this theme. In addition, the word "theme" as a general term can imply any swatch of any theme.
The CSS file of any swatch is self-sufficient and contains all required styles for the Telerik Blazor components, except the optional font icon styles. You can switch the theme runtime, but the Blazor app should always load only one theme at a time.
Integration with the Telerik Components
The CSS themes represent an external dependency to Telerik UI for Blazor:
- The themes represent a separate product, which is used by multiple Telerik and Kendo UI products. Each Telerik UI for Blazor version is compatible with specific theme versions.
- The Telerik and Kendo UI Themes documentation is part of the Progress Design System Kit documentation. The content in the Telerik UI for Blazor documentation is introductory or specific only to the Blazor components.
- The Telerik and Kendo UI Themes have their own product development, roadmap and strategy. You can log public feature requests or bug reports on the Telerik Themes feedback portal.
Built-in Themes
The Themes - Get Started page lists the built-in themes in Telerik UI for Blazor and describes their unique specifics.
Comparing Themes and Swatches
You can explore and compare the built-in theme swatches on the live Telerik UI for Blazor demos. Use the Change Theme dropdown above each component example. To test how the available swatches affect the appearance of the Telerik UI for Blazor components, you can also check the ThemeBuilder app. This tool provides the ability to customize the existing themes and swatches.
Using a Theme
To register a theme, you must reference its stylesheet in the <head> of the web page. The exact project file that contains the <head> tag depends on the .NET version and the Blazor application type. See our Getting Started guides for more information.
There are three ways to load a Telerik theme, in terms of physical CSS file location. Note that each option provides access to a different number of theme swatches.
-
Load a CSS theme as a static asset from the
Telerik.UI.for.BlazorNuGet package. This is the easiest option and it doesn't require maintenance during Telerik UI for Blazor version upgrades. However, you can use only the Main swatch of each theme and the Ocean Blue swatch of the Default theme. - Load a CSS theme from a remote URL, for example, CDN. The dedicated documentation of each theme provides a list of swatches and their URLs.
- Load a CSS theme as a local file in the
wwwrootfolder in the Blazor app. This option is relevant to the following cases:- When using custom themes.
- When creating or converting Telerik Blazor apps with the Telerik UI for Blazor Visual Studio extension.
- When using themes from the Telerik UI for Blazor MSI installer or ZIP archive. The CSS files are in the
swatchesfolder. - When using LibMan or npm to obtain a specific Telerik theme version. In this case, you can use all built-in theme swatches.
The Blazor app must load only one Telerik theme file at a time. Upgrade the theme with every Telerik UI for Blazor version upgrade, unless you are loading the theme as a static NuGet asset.
Loading Themes from the NuGet Package
The easiest way to load a Telerik theme in a Blazor app is to reference a static asset from the NuGet package. The .NET SDK will copy the CSS file to the output folder during build automatically. Static assets provide the following benefits:
- The application relies on available local resources, instead of third parties and remote URLs.
- The theme URL does not change across component versions, which makes product updates easier. Add a cache buster to avoid possible browser caching issues.
The Telerik.UI.for.Blazor NuGet package includes only the Main swatch of each theme and the Ocean Blue swatch of the Default theme. The code snippet below shows all available CSS files in the NuGet package and their correct URLs. To use another swatch, see the section Using a Theme above.
Load a Telerik theme as a static NuGet asset
<head>
<!-- Choose only one theme. -->
<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/all.css" />
<!--
<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-default/default-ocean-blue.css" rel="stylesheet" />
<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-bootstrap/all.css" rel="stylesheet" />
<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-material/all.css" rel="stylesheet" />
<link href="_content/Telerik.UI.for.Blazor/css/kendo-theme-fluent/all.css" rel="stylesheet" />
-->
</head>
Trial users must add
.Trialto the theme URL:
<link rel="stylesheet" href="_content/Telerik.UI.for.Blazor.Trial/css/kendo-theme-default/all.css" />
Compatibility and Maintenance
The Telerik themes are decoupled from the Telerik Blazor components, which leads to the following usage requirements:
- When using a CSS theme as local file in
wwwroot, replace the file every time you change the Telerik UI for Blazor version. This includes apps created with the Telerik Blazor Visual Studio extension without CDN support. - When loading theme swatches from a CDN, make sure that the theme version is compatible with the Telerik UI for Blazor version. Our release notes provide theme compatibility information for each components version. You can also use a newer minor theme version, which doesn't contain breaking changes. In other words, the latest major theme version may be still incompatible with the latest version of Telerik UI for Blazor.