Custom Themes
By customizing themes, you can alter the default appearance of the Telerik components so they match the desired color scheme and the rest of your site's coloring and style.
This article contains the following sections:
- Using the ThemeBuilder
- Manual Alternative
- Comparing the Blazor CSS Customization Approaches
- How to Use a Custom Theme I Have
- Contribution
When you use custom themes for Telerik UI for Blazor components, you must re-generate the custom theme every time you updates the Telerik components in your project. This allows you to get the theme updates and fixes.
Using ThemeBuilder
ThemeBuilder is a web application that enables you to create new themes and customize existing ones. Every change that you make is visualized almost instantly. Once you are done styling the UI components, you can export a zip file with the styles for your theme and use them in your Blazor app.
Manual Alternative
Each Kendo UI theme package includes the source files of the respective theme and, thus, provides options for you to modify and rebuild the theme as part of your build process.
For example, you can change the theme colors, remove the CSS of unused components, or use specific theme colors to style your application. The theme source files are located in the scss folder of the theme package.
For the full list of variables that can be modified in a theme, refer to the Using Variables section.
To build a custom theme by using the theme variables, apply either of the following approaches:
- (Recommended) Use the build process of your application—This approach simplifies the upgrades to new theme package versions.
- Use the build process of the themes—This approach requires you to build the theme each time the theme packages are updated.
Using the Build Process of the Application
When you want to built the Telerik themes yourself (for example, to combine them with the rest of your styles in to one stylesheet), review the following article first, before continuing with the steps below: https://github.com/telerik/kendo-themes/wiki/Compiling-themes.
To customize a Sass-based theme, create a .scss
file and consume the theme package in the following way:
-
Obtain the theme source through the NPM package.
npm install @progress/kendo-theme-default
Create a
.scss
file that will consume the theme. For the purposes of the example, this isstyles.scss
.-
To build the theme files, import them into the
styles.scss
file.@import "node_modules/@progress/kendo-theme-default/dist/all.scss";
The
dist/all
file adds the styles for all components that are available in the theme. To trim down the size of the generated CSS, import only the source for the components that you use in your application. Each of them could be found inscss/
folder.// Import only the Grid and TreeView styles using Node Sass @import "~@progress/kendo-theme-default/scss/grid/_index.scss"; @import "~@progress/kendo-theme-default/scss/treeview/_index.scss"; // or using Dart Sass @import "~@progress/kendo-theme-default/scss/grid/"; @import "~@progress/kendo-theme-default/scss/treeview/";
-
To customize the variables that are used in the theme, change the theme before you import the theme files.
$primary: #E82C0C; // brand color @import "~@progress/kendo-theme-default/dist/all.scss";
-
Build the
styles.scss
file through a Sass compiler.To use Node Sass (which uses LibSass), install the compiler with
npm install node-sass --save
and then compile the file with the following commandnode-sass styles.scss styles.css
To use Dart Sass, install the compiler with
npm install node-sass@npm:sass --save
and then compile the file with the following commandsass styles.scss styles.css
Using the Build Process of the Themes
While each Sass-based theme has a dedicated NPM package (for example, @progress/kendo-theme-default), the source code for all themes is located in the kendo-themes repository which contains a build task that compiles the theme sources to CSS. To customize a theme, modify the source code of the theme and use the build task to produce a CSS file for your application. This approach avoids the need for a setting up a build configuration when you compile SCSS, but may be harder to maintain as the process has to be repeated each time we update a theme.
You have two options to do that (described in turn below):
- Customizing Themes with Swatches
- Customizing the Source Code
- Creating Custom Components Bundle
Customizing Themes with Swatches
A swatch is a set of variables which customizes the appearance of the theme.
- Each swatch is placed in a separate file. A theme may contain multiple swatches.
- Swatches are useful for creating multiple, persistent theme variations.
- The
.css
output file can be shared across projects and requires no further processing.
To create a swatch:
- Clone the kendo-themes GitHub repository.
- Install the node-gyp package.
- Install the dependencies for all themes with
npm install && npx lerna bootstrap
. - Switch the working directory to
packages/<THEME_NAME>
. - Create a
SWATCH_NAME.scss
swatch file in thescss/swatches
folder. - To build the swatches for the theme by running
npm run sass:swatches
ornpm run dart:swatches
. - Include the compiled CSS swatch file in your project. It could be found under
dist/SWATCH_NAME.css
.
For example, in the Material theme create blue-pink-dark
swatch with the following lines:
// Variables.
$primary-palette-name: blue;
$secondary-palette-name: pink;
$theme-type: dark;
// Import the theme file for the components you use.
@import "../panelbar/_index.scss";
@import "../grid/_index.scss";
// Alternatively, include all components.
@import "../all.scss";
For the Default and Bootstrap themes, the swatch should look like:
// Variables.
$primary: blue;
$secondary: pink;
// Import the theme file for the components you use.
@import "../panelbar/_index.scss";
@import "../grid/_index.scss";
// Alternatively, include all components.
@import "../all.scss";
Customizing the Source Code
To create a custom theme by modifying the themes source code:
- Clone the kendo-themes GitHub repository.
- Install the dependencies for all themes with
npm install && npx lerna bootstrap
. - Customize the theme variables in the
packages/THEME_NAME/scss/_variables.scss
files. - Build the themes with the
npm run sass
ornpm run dart
command to create the customized version of the themes in thepackages/THEME_NAME/dist/all.css
file. - After the build completes, reference the compiled CSS in your application.
Creating Custom Components Bundle
You might want to omit the styles for some components in the CSS output. To include only the styles that you need:
- Clone the kendo-themes GitHub repository.
- Install the dependencies for all themes with
npm install && npx lerna bootstrap
. - Switch the working directory to
packages/<THEME_NAME>
. -
Create a
CUSTOM_THEME.scss
file in thescss
folder. For example, createcustom.scss
file with the following lines:// Import the theme file for the components you use. @import "../panelbar/_index.scss"; @import "../grid/_index.scss";
To build the file, navigate to the theme folder and run
gulp sass --file "scss/CUSTOM_THEME.scss"
.- Include the compiled CSS file in your project. It could be found under
dist/CUSTOM_THEME.css
.
Using Variables
The following list describes the theme variables available for adjustment in the Kendo UI Default theme.
The following example demonstrates how to use common variables.
Name | Default value | Description |
---|---|---|
$font-size | 14px | Base font size across all components. |
$font-family | inherit | Font family across all components. |
$font-family-monospace | Consolas, "Ubuntu Mono", "Lucida Console", "Courier New", monospace | Font family for monospaced text. Used for styling the code. |
$line-height | (20 / 14) | Line height used along with $font-size. |
$border-radius | 2px | Border radius for all components. |
$accent | #ff6358 | The color that focuses the user attention. Used for primary buttons and for elements of primary importance across the theme. |
$accent-contrast | #ffffff | The color used along with the accent color denoted by $accent. Used to provide contrast between the background and foreground colors. |
$base-text | #656565 | The text color of the components' chrome area. |
$base-bg | #f6f6f6 | The background of the components' chrome area. |
$base-border | rgba( black, .08 ) | The border color of the components' chrome area. |
$base-gradient | $base-bg, darken( $base-bg, 2% ) | The gradient background of the components' chrome area. |
$hovered-text | #656565 | The text color of hovered items. |
$hovered-bg | #ededed | The background of hovered items. |
$hovered-border | rgba( black, .15 ) | The border color of hovered items. |
$hovered-gradient | $hovered-bg, darken( $hovered-bg, 2% ) | The gradient background of hovered items. |
$selected-text | $accent-contrast | The text color of selected items. |
$selected-bg | $accent | The background of selected items. |
$selected-border | rgba( black, .1 ) | The border color of selected items. |
$selected-gradient | none | The gradient background of selected items. |
$error | #f5503e | The color for error messages and states. |
$warning | #fdce3e | The color for warning messages and states. |
$success | #5ec232 | The color for success messages and states. |
$info | #3e80ed | The color for informational messages and states. |
The following example demonstrates how to configure the Buttons.
Name | Default value | Description |
---|---|---|
$button-text | $base-text | The text color of the buttons. |
$button-bg | $base-bg | The background of the buttons. |
$button-border | $base-border | The border color of the buttons. |
$button-gradient | $base-gradient | The background gradient of the buttons. |
$button-hovered-text | $hovered-text | The text color of hovered buttons. |
$button-hovered-bg | $hovered-bg | The background of hovered buttons. |
$button-hovered-border | $hovered-border | The border color of hovered buttons. |
$button-hovered-gradient | $hovered-gradient | The background gradient of hovered buttons. |
$button-pressed-text | $selected-text | The text color of pressed buttons. |
$button-pressed-bg | $selected-bg | The background color of pressed buttons. |
$button-pressed-border | $selected-border | The border color of pressed buttons. |
$button-pressed-gradient | none | The background gradient of pressed buttons. |
$button-focused-shadow | 0 3px 4px 0 rgba(0, 0, 0, .06) | The shadow of focused buttons. |
The following example demonstrates how to configure the Charts.
Name | Default value | Description |
---|---|---|
$series-a | #ff6358 | The color of the first series. |
$series-b | #ffd246 | The color of the second series. |
$series-c | #78d237 | The color of the third series. |
$series-d | #28b4c8 | The color of the fourth series. |
$series-e | #2d73f5 | The color of the fifth series. |
$series-f | #aa46be | The color of the sixth series. |
$chart-major-lines | rgba(0, 0, 0, .08) | The color of the Chart grid lines (major). |
$chart-minor-lines | rgba(0, 0, 0, .04) | The color of the Chart grid lines (minor). |
The following example demonstrates how to configure the Toolbar.
Name | Default value | Description |
---|---|---|
$toolbar-padding-x | $padding-x | The horizontal padding of the container. |
$toolbar-padding-y | $padding-x | The vertical padding of the container. |
Comparing the Blazor CSS Customization Approaches
You can customize the appearance of the Telerik Blazor components in three ways. Each has pros and cons, and each is most suitable for specific scenarios and business requirements. The Blazor Theme Customization Options article offers a comparison between these CSS customization approaches.
How to Use a Custom Theme I Have
You have your custom theme - either generated through the Telerik ThemeBuilder tool, or one that you built yourself, or something that your organization provides.
To use that, instead of one of the built-in themes, you need to:
Add the customized
.css
file to your application, usually in thewwwroot
folder. For example, it can be in a folder calledmyCustomTelerikThemes
and the file itself could be calledSomeCustomTheme.css
.-
Include the custom stylesheet file in the
head
tag of your index document (by defaultwwwroot/index.html
for WebAssembly apps and~/Pages/_Host.cshtml
for server-side Blazor apps). This could looks something like this:Index file
<head> <!-- More content can be present here --> <link rel="stylesheet" href="myCustomTelerikThemes/SomeCustomTheme.css" /> <!-- More content can be present here --> </head>
Make sure that this is the only Telerik Theme that is referenced in the application. If you are using a built-in theme, you must remove its
<link>
element.
Contribution
To contribute to the development of the Kendo UI Default Theme, refer to the telerik/kendo-themes GitHub repository it is stored in.