DevExtreme React - ThemeBuilder

The ThemeBuilder allows you to create custom themes based on Bootstrap or predefined DevExtreme themes. It consists of a UI version (illustrated below) and a command-line interface (CLI).

DevExtreme ThemeBuilder UI: Main View

IMPORTANT
The ThemeBuilder works only with HTML-based UI components. To create a custom theme for an SVG-based UI component, follow the instructions from this article.

Get Started

Once you open the ThemeBuilder, a theme configuration wizard appears. You can choose whether to create a new theme or import an existing DevExtreme or Bootstrap theme.

Create a New Theme

New themes are based on predefined DevExtreme themes. Follow these steps to create a new theme in the wizard:

  1. Click Choose a Base Theme.

  2. Select a base theme: Generic or Material.

  3. Select a color scheme and change basic appearance settings.

  4. After you changed the basic settings, you can click Export to export the theme to a stylesheet. We also recommend that you export your theme's metadata. You need it to update your custom theme if you decide to migrate to a future DevExtreme version.
    If you need more customization options, click Advanced Settings.

Import an Existing Theme

You can import an existing theme from DevExtreme metadata saved beforehand or from Bootstrap variables. Follow the steps below to do that in the wizard:

  1. Click Import a Theme.

  2. Choose whether to import a theme from DevExtreme metadata or Bootstrap variables.

  3. To import DevExtreme metadata, upload a .json file with the metadata or paste the metadata in the text area.

    To import Bootstrap variables, upload a variables.less for Bootstrap 3 or _variables.scss file for Bootstrap 4/5. The ThemeBuilder uses colors from the variables to create a theme that is consistent with the Bootstrap theme.

After you import a theme, the wizard navigates to the main view for additional theme customization.

Customize the Theme

After you create or import a theme, the ThemeBuilder navigates you to the main view where you can customize the theme.

DevExtreme ThemeBuilder UI: Main View

The main view consists of the following elements:

  • Settings list (left-hand menu)
    Contains all customization settings divided into groups:

    • Basic Settings - settings used by multiple UI components

    • Typography Settings - settings that configure fonts

    • Specific UI components or UI component groups - settings used by an individual UI component or UI component group

    The settings list also contains a search box to search for a UI component or UI component group.

  • Toolbar (top panel)
    Contains the theme switcher and Import and Export buttons.

  • Preview area
    Displays DevExtreme components in the customized theme. Updates automatically when you change a setting or switch between themes.

Postpone Customization

To return to customization later, save the theme's metadata in advance. Click Export on the toolbar to open the Theme Export popup dialog. In this dialog, enter the color scheme name.

DevExtreme ThemeBuilder UI: Theme Export popup dialog, Enter Name

Go to the Choose Format step and click the Download Metadata File button.

DevExtreme ThemeBuilder UI: Theme Export popup dialog, Choose Format

A .json file with metadata is saved on your computer. Alternatively, you can Copy Metadata.

To continue customization, click Import on the toolbar. In the invoked Theme Import dialog, click Upload File and select the .json file that you exported previously. If you copied the metadata rather than exported it as a .json file, paste it in the text area and click Upload Metadata:

DevExtreme ThemeBuilder UI: Theme Import popup dialog

Export the Resulting Theme

Click Export to open the Theme Export popup dialog. In this dialog, enter the color scheme name. If you want to export the theme as a color swatch, check the check box. You can also remove links to external resources, such as fonts.

DevExtreme ThemeBuilder UI: Theme Export popup dialog, Enter Name

On the next step, select the components for your theme to support.

DevExtreme ThemeBuilder UI: Theme Export popup dialog, Select Widgets

Click Download CSS File to save a file named dx.[base-theme-name].[color-scheme-name].css (for example, dx.material.brown.css) on your computer. Alternatively, you can download the archive with a CSS file and icons or copy the CSS.

DevExtreme ThemeBuilder UI: Theme Export popup dialog, Choose Format

Your custom theme uses icons and fonts. They should be located next to the theme. When you use npm, you can find the icons and fonts folders in node_modules/devextreme/dist/css. In other cases, these folders are in the directory with predefined themes. Copy them to the directory that contains your theme.

Finally, register the exported theme. If you exported a color swatch, apply it as described in Color Swatches.

NOTE
We periodically remove and remap unused constants to optimize our predefined themes. This can cause compatibility issues when you upgrade custom themes. We recommend that you save your theme's metadata to enable you to fix these issues. Refer to the Postpone Customization topic for more information.

ThemeBuilder CLI

The ThemeBuilder CLI allows you to generate themes programmatically or at build time. This tool is part of the DevExtreme CLI.