Classic Theme Customization (SCSS)

• Jul 30, 2025
• 5 minutes to read

This topic describes how DevExpress theme styles are organized. It also includes step-by-step instructions on how to customize DevExpress Classic themes.

Important

Fluent themes do not support SCSS customizations.

How DevExpress Blazor Theming Works

DevExpress Blazor Classic 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 in 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 25.1\Components\Sources\Blazor\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 source: Bootstrap v5.3.

Customize a DevExpress Classic Theme

Follow the instructions described in the sections below to create a custom theme based on a DevExpress Classic 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 25.1\Components\Sources\Blazor\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 25.1/Components/Sources/Blazor/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 25.1/Components/Sources/Blazor/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
   

Note

In some cases, a change to an SCSS variable will not produce the desired visual effect due to complex dependencies within the theme’s structure. If you encounter issues when you attempt to modify the variable, define a custom CSS rule to target the specific element directly.

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. Blazor Web. Create a theme using the DxTheme constructor and call the RegisterTheme(ITheme) method to apply the theme:

   Components/App.razor

   <head>
       @*...*@
       @DxResourceManager.RegisterTheme(customTheme)
       <link href=@AppendVersion("css/site.css") rel="stylesheet" />
   </head>
   @code{
       ITheme customTheme = new DxTheme("MyCustomTheme", ["css/theme.css", "css/theme-color.css"]);
       private string AppendVersion(string path) => FileVersionProvider.AddFileVersionToPath("/", path);
   }
   

3. Blazor Hybrid. Replace the previous stylesheet link with new stylesheet links in the index.html file:

   index.html

   <head>
       @*...*@
       <link href="css/theme.css" rel="stylesheet" />
       <link href="css/theme-color.css" rel="stylesheet" />
       <link href="css/app.css" rel="stylesheet" />
   </head>
   

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

For more information on how to apply a theme in DevExpress Blazor applications, refer to the following article: Themes.

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.