Sass-Based Themes

As of the R1 2017 release, the Kendo UI distribution includes Sass-based themes.

Currently, Kendo UI delivers the following Sass themes:

Kendo UI Default v.2—The latest update of the Kendo UI Default theme.
Kendo UI Bootstrap v.4—To achieve similarity with the Bootstrap look and feel, the theme has linked variables to Bootstrap. This means that customizing the original Bootstrap theme will affect the Kendo UI theme as well.
Kendo UI Material—An update of the Kendo UI Material Theme to closely implement the Material Design Guidelines.
Kendo UI Classic—An SCSS-based variant of the Less Default theme.

Less- vs. Sass-Based Themes

Apart from being written in a different language, the Sass-based themes are slightly different from the Less-based ones. This article outlines those differences and demonstrates how to use the Sass-based themes.

In Kendo UI, the Sass-based themes demonstrate the following differences from the Less-based ones:

Each Sass-based theme is represented by a single CSS file that combines the layout and the themes of the components. As a result, you do not need to match a theme with its common file.
Based on the widget you work with, the Sass-based themes can build a part of the widget theme in a similar way the Download Builder trims unused scripts.
The Sass-based themes are available on NPM. Each theme is stored as an NPM package and can be easily upgraded.
Each Sass-based theme is compatible with the Kendo UI components for Angular. This enables you to port parts of your application to Angular 2 while maintaining their styling.

Browser Limitations

The following CSS features, which are used by the Sass-based themes, provide limited browser support:

Flexbox layout—Not supported by Internet Explorer 10 and earlier.
CSS gradients—Not supported by Internet Explorer 9 and earlier.
Web Open Font Format—Not supported by Internet Explorer 8 and earlier.
Border radius—Not supported by Internet Explorer 8 and earlier.
Alpha transparency colors—Not supported by Internet Explorer 8 and earlier.

Getting the Themes

To get the Sass-based Kendo UI themes, you can:

Use the pre-built CSS files.
Use the NPM packages.

Using Pre-Built CSS

To get a complete theme by using its pre-built CSS files, apply either of the following approaches:

Use the CSS files that are shipped with the Kendo UI distribution. For example, the Default v2 theme is distributed as styles/kendo.default-v2.min.css.
Use the NPM package which contains a pre-built dist/all.css CSS file for the theme. For more information on how to obtain the NPM package, refer to the following section on using NPM packages.

Using NPM Packages

The Kendo UI Sass-based themes are located on the Progress NPM registry:

Kendo UI Default Theme—Available as @progress/kendo-theme-default.
Kendo UI Bootstrap v4 Theme—Available as @progress/kendo-theme-bootstrap.
Kendo UI Material Theme—Available as @progress/kendo-theme-material.
Kendo UI Classic Theme—Available as @progress/kendo-theme-classic.

To access the Progress NPM registry, you need an active Telerik account with an active commercial license. For more information on how to access the NPM registry, refer to the installation instructions for Kendo UI Professional.

Customizing the Themes

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

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 is styles.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 in scss/ 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 command
```
node-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 command
```
sass 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 a theme is updated.

Customizing Themes with Swatches

A swatch is a set of variables which customizes the appearance of the theme.

Swatches are useful for creating multiple, persistent theme variations.
A theme may contain multiple swatches.
Each swatch is placed in a separate json config file.
The .css output file can be shared across projects and requires no further processing.

In order to utilize the Kendo Themes infrastructure for building and creating swatches, first setup the repository:

Clone the kendo-themes GitHub repository.
Install the node-gyp package.
Install the dependencies for all themes with npm install && npm run bootstrap.

To compile existing swatches:

Run the sass:swatches task from the root of the repository
```
npm run sass:swatches
```
Include one of the compiled CSS swatch files(packages/<THEME_NAME>/dist/SWATCH_NAME.css) in your project.

To create a new swatch:

Create a <THEME_NAME>-<SWATCH_NAME>.json file in the packages/<THEME_NAME>/lib/swatches folder.
Follow the already existing (<THEME_NAME>-main.json schema for customizing the variables.
Run the sass:swatches task from the root of the repository.
Include one of the compiled CSS swatch files(packages/<THEME_NAME>/dist/SWATCH_NAME.css) in your project.

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 or npm run dart command to create the customized version of the themes in the packages/THEME_NAME/dist/all.css file.
After the build completes, reference the compiled CSS in your application.

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.

Contribution

To contribute to the development of the Kendo UI Default Theme, refer to the telerik/kendo-themes GitHub repository it is stored in.

Using the Sass Theme Builder

Progress Sass Theme Builder for Kendo UI is an Angular web application that enables you to create new or customize existing themes.

The tool renders the same look and feel as the look and feel of all other components in the suite. It also delivers full control over the skin elements of each component and automatically updates its composite units. After you create the skin and achieve the desired look of the theme, the Sass Theme Builder enables you to download and integrate it in your project.

Figure 1: A preview of the Sass Theme Builder

Theme Builder Overview

Using Newly Created Themes

To create a new theme:

On the initial Sass Theme Builder pane, select the Start Theming option.
Choose one of the existing themes to serve as a starting point.
Select the widgets which you intend to style. You can also change the selection at a later stage.

Figure 2: Selecting a base theme and widgets

Complex widgets, such as the Grid, rely on other widgets to deliver their full set of features. If you select the Grid, then all of its widgets dependencies styles (Button, AutoComplete, DropDownList, DatePicker, etc.) will also be included in the final bundle. The Theme Builder automatically updates the styling on all required widgets so that you do not need to customize each of them separately.

Modifying Themes

The Sass Theme Builder supports the following options for customization:

Color pickers which customize the appearance of the components.
The Apply changes instantly option which enables you to observe the changes on the fly.
Manual updates of each component element.
Utilization of predefined color swatches.

To customize an existing theme, use the following Sass Theme Builder features:

Color swatches—Contains predefined color palettes that you can apply to all widgets in your application.
Default—Provides the applicable color customization options.
Selected Widgets—List of widgets to include in the preview and the final CSS bundle.
Download—Downloads the archive that holds the generated style files after the customization completes. When you click the button, a dialog appears and prompts you to name your theme.

Figure 3: Available options for customization

Theme Builder Create and Download 3

To upload an existing theme you have previously created:

On the initial Sass Theme Builder pane, select Import Theme.
Upload the variables.scss file which contains your current modifications of the customized theme. As a result, the selected components and styling elements load.
Start customizing your theme.

Figure 4: Importing themes for customization

Themebuilder import existing theme

When you complete the modifications and the theme is ready to be used:

Download the theme as a compact archive by clicking the Download button.
Add the newly created Theme folder to your application.
Include the THEME_NAME.css file in the head tag of your HTML document.

Avoid referencing the kendo.common.min.css and kendo.rtl.min.css files because the exported CSS file contains all styles you need.