DevExpress Theme Customization

• Sep 24, 2024
• 6 minutes to read

This topic describes how DevExpress theme styles are organized. It also includes step-by-step instructions for DevExpress theme customization.

How DevExpress Blazor Theming Works

DevExpress Blazor themes use SCSS to implement styles. SCSS variables are identified by the $ character at the beginning. Since browsers do not natively support SCSS code, all source code is compiled into a CSS file – a DevExpress built-in theme.

A built-in DevExpress theme includes both DevExpress and Bootstrap CSS rules. To customize these rules, override DevExpress or Bootstrap SCSS variable values, respectively. Components that use DevExpress rules are listed below:

Show Components List

Accordion Button Calendar Chart CheckBox ComboBox Context Menu DropDown

Flyout Form Layout Date Edit Grid Grid Layout List Box Loading Panel Masked Input

Memo Menu Pager Popup Rich Text Editor Scheduler Spin Edit Stack Layout

Tabs TagBox Text Box Time Edit Toolbar TreeView Wait Indicator Window

For more information about CSS and SCSS variables refer to SASS documentation: SASS:Variables.

DevExpress SCSS Variables

DevExpress SCSS variable names include a dx prefix. These variables define the appearance of DevExpress Blazor components that use our own CSS selectors. For instance, the dx-grid-bg and dx-grid-color variables allow you to customize the appearance of the Grid component:

scss

$dx-grid-bg: #fff8e7 !default;
$dx-grid-color: #8b1a1a !default;
$dx-grid-header-bg: #efbbcc !default;
$dx-grid-header-color: #480607 !default;

You can find the complete list of DevExpress variables in files located in the themes folder. The default full path to these files is C:\Program Files\DevExpress 24.1\Components\Sources\DevExpress.Blazor.Themes\scss\components.

Bootstrap SCSS Variables

Bootstrap SCSS variables define the appearance of components that use Bootstrap CSS selectors. For instance, you can override values of the body-bg and body-color variables to customize the appearance of a DevExpress template page that uses Bootstrap selectors:

scss

$body-bg: #f0f8ff !default;
$body-color: #6d9bc3 !default;

For more information on how to override Bootstrap variables, refer to the following sources:

• Bootstrap v4.6
• Bootstrap v5.3

Customize a Built-in Theme

Follow the instructions described in the sections below to create a custom theme based on a DevExpress theme.

Note

SCSS files, including SCSS variables, are part of DevExpress source code. If you install a new DevExpress version, theme customizations may stop working. Refer to the following section for more information on how to upgrade a custom theme: Upgrade a Custom Theme to a New Version. The DevExpress support team cannot assist you with such upgrade issues. For additional information, please review Limitations on DevExpress Support Services.

Set Up the Environment

1. Install Node.js and npm if needed.

2. Navigate to the folder with DevExpress themes. The default path is
   C:\Program Files\DevExpress 24.1\Components\Sources\DevExpress.Blazor.Themes.

3. In this folder, run a console as an administrator and execute the following command to install dependencies:

   npm i
   

4. On your local disk that stores DevExpress Blazor components, create a folder to store the resulting theme. Change the console’s current directory to this folder.

   cd <path-to-resulting-theme-folder>
   

5. Execute the following command to generate the package.json file. Specify the package name property. You can skip the other package settings.

   npm init
   

6. Execute the following command to install the SASS dependency:

   npm i sass -save-dev
   

Set Up the Theme Build

1. In the folder with the package.json file, create a file with a *.scss extension. For example, name the file scss-file-name.scss.

2. In the package.json file, replace the Scripts attribute value with the following string:

   package.json

   "scripts": {
       "build": "sass ./<scss-file-name>.scss:<output-css-dir>/<theme-name>.css"
   },
   

   When you execute a command to build your theme’s stylesheet, this script creates the <output-css-dir> folder and builds the <theme-name> stylesheet in this folder.

3. Open the scss-file-name.scss file and reference the DevExpress theme’s source file. For example, if the <output-css-dir> folder is in the root of the C:\ drive, the relative path is the following:

   scss-file-name.scss

   @import "../Program Files/DevExpress 24.1/Components/Sources/DevExpress.Blazor.Themes/scss/blazing-berry/blazing-berry.bs5.scss";
   

   Note that SASS uses URLs to import files (not file paths). That is why you need to use forward slashes regardless of your machine’s operating system. For more information on how to import stylesheets in a .scss file, refer to SASS documentation: @import.

Change Values of SCSS Variables

1. Before the @import statement, override default values of Bootstrap and/or DevExpress SCSS variables:

   scss-file-name.scss

   /* Bootstrap variables */
   $body-bg: #f0f8ff;
   $body-color: #6d9bc3;
   /* DevExpress variables */
   $dx-grid-bg: #fff8e7;
   $dx-grid-color: #8b1a1a;
   $dx-grid-header-bg: #efbbcc;
   $dx-grid-header-color: #480607;
   
   @import "../Program Files/DevExpress 24.1/Components/Sources/DevExpress.Blazor.Themes/scss/blazing-berry/blazing-berry.bs5.scss";
   

2. In your theme’s folder, execute the following command to build the stylesheet:

   npm run build
   

Integrate a Custom Theme Into Your Application

1. Copy this stylesheet from the <output-css-dir> folder to the wwwroot/css folder of your project.

2. Replace the link to the old stylesheet with a link to the newly added stylesheet in one of the following layout files:

   • Pages/_Layout.cshtml for Blazor Server applications created with a Microsoft template in .NET 6
   • Pages/_Host.cshtml for Blazor Server applications created with a DevExpress Template in .NET 6 and .NET 7 or with a Microsoft template in .NET 7
   • wwwroot/index.html for Blazor WebAssembly or Hybrid applications in .NET 6 and .NET 7
   • Components/App.razor for Blazor Web applications in .NET 8 and .NET 9

   If you do not implement any solutions to refresh cached resources on user machines, inject the IFileVersionProvider interface in the layout file. If you did not create the project from the DevExpress template, you also need to add the corresponding service in the Program.cs file:

   builder.Services.AddMvc();
   

   The interface ensures that web browsers on user machines use the actual version of DevExpress CSS resources instead of the previously cached version. Refer to HTTP caching for more information about the browser cache.

   @using Microsoft.AspNetCore.Mvc.ViewFeatures
   @inject IFileVersionProvider FileVersionProvider
   
   <head>
       @*...*@
       <link href=@AppendVersion("css/<theme-name>.css") rel="stylesheet" asp-append-version="true" />
       <link href=@AppendVersion("css/site.css") rel="stylesheet" />
       @*...*@
   </head>
   
   @* .NET 8 and .NET 9 *@
   @code {
       private string AppendVersion(string path) => FileVersionProvider.AddFileVersionToPath("/", path);
   }
   @* .NET 6 *@
   @{
       string AppendVersion(string path) => FileVersionProvider.AddFileVersionToPath("/", path);
   }
   

3. Build your project. You can now see the modified theme.

Upgrade a Custom Theme to a New Version

You may need to update your custom theme when you upgrade Blazor components to a new version (major or minor):

• Update custom selectors if you specified them on a theme level.
• Rebuild your theme with a new theme’s source file. Start with the Set Up the Theme Build section.