Devextreme Theming

DevExtreme Theming Skill

When to Use This Skill

• Applying a predefined DevExtreme theme to a project.
• Creating a custom theme with ThemeBuilder (UI or CLI).
• Overriding theme styles with CSS classes or component elementAttr.
• Implementing dark/light mode or runtime theme switching.
• Using color swatches for mixed-theme layouts.
• Setting up SCSS-based theme imports.

---

Before You Start

> ⚠️ Always use DevExtreme theme CSS imports and themes.current() from devextreme/ui/themes for runtime switching. Never manually swap CSS classes on document.body, use Bootstrap, Ant Design, Material UI, or any other theming system. For scoped section overrides, use .dx-swatch-* wrapper classes — do not edit DevExtreme's internal CSS files directly.

Architecture Overview

DevExtreme Theme Pipeline
──────────────────────────────────────────────────────────────────
  Option A │ Import prebuilt CSS  →  dx.[theme].css
  Option B │ SCSS import  →  devextreme/scss/bundles/dx.[theme].scss
  Option C │ ThemeBuilder UI/CLI  →  export dx.[base].[color].css
──────────────────────────────────────────────────────────────────
  Runtime  │ DevExpress.ui.themes.current(name)  — same theme family
  Swatch   │ .dx-swatch-xxx wrapper class  — section-level overrides
  CSS API  │ .dx-* classes / elementAttr / wrapperAttr  — component-level

---

Theme Families

| Family | Base name pattern | Notes | |---|---|---| | Generic | generic.light, generic.dark, generic.contrast, generic.carmine, etc. | Also compact variants: generic.light.compact | | Material Design | material.blue.light, material.blue.dark, material.teal.light, etc. | Color + mode segments | | Fluent | fluent.blue.light, fluent.blue.dark, etc. | Requires icon archive when exporting |

CSS file name pattern: dx.[theme-family].[color-variant].css Examples: dx.light.css, dx.dark.css, dx.material.blue.light.css, dx.fluent.blue.light.css

> Compact themes reduce all component sizes. Use these instead of zoom/transform CSS — DevExtreme does not support those properties.

---

Documentation Reference

| Topic | Reference File | |---|---| | Predefined themes — applying and CSS file names | [references/predefined-themes.md](references/predefined-themes.md) | | ThemeBuilder UI and CLI — creating custom themes | [references/themebuilder.md](references/themebuilder.md) | | Custom CSS overrides — classes, elementAttr, defaultOptions | [references/custom-css.md](references/custom-css.md) | | Runtime theme switching and color swatches | [references/runtime-switching.md](references/runtime-switching.md) | | Icons — built-in library, custom icons, external libraries, Fluent archive setup | [references/icons.md](references/icons.md) |

---

Quick-Start: Apply a Theme

React / Vue (Vite)

// main.ts or main.tsx — import exactly ONE theme
import 'devextreme/dist/css/dx.fluent.blue.light.css';

Angular

// angular.json — add to "styles" array
"styles": [
  "node_modules/devextreme/dist/css/dx.fluent.blue.light.css",
  "src/styles.css"
]

jQuery

> Only one prebuilt theme should be active at a time. For runtime switching, see [references/runtime-switching.md](references/runtime-switching.md).

---

Key API

| API | Description | |---|---| | DevExpress.ui.themes.current() | Returns the currently active theme name | | DevExpress.ui.themes.current(name) | Switches to another theme in the same family (no page reload) | | DevExpress.ui.themes.ready(callback) | Fires after a theme finishes loading | | elementAttr | Adds CSS classes or attributes to a component's root element | | wrapperAttr | Adds CSS classes to a popup/overlay wrapper element (Popup, Tooltip, etc.) | | defaultOptions(rule) | Sets default options for all instances of a component type |

---

Constraints and Rules

1. One theme family at a time. You cannot mix Generic and Material themes on the same page without color swatches. Switching between families requires a page reload.
2. Compact is the right way to reduce size. DevExtreme does not support zoom or transform for sizing. Use compact theme variants instead.
3. DevExpress.ui.themes.current() only works within a theme family. Cross-family switches (e.g., Generic → Material) need page reload with localStorage/sessionStorage persisting the choice.
4. Color swatches cannot style SVG-based components. SVG components (Chart, PieChart, Gauge, etc.) use separate JSON-based theme configurations, not CSS.
5. ThemeBuilder is for HTML-based components only. For SVG-based components, use the palette and theme component options.
6. CSS class overrides may break on DevExtreme upgrades. Internal markup structure can change without notice. Prefer the component API (elementAttr, defaultOptions) over .dx-* class overrides.
7. Angular/Vue scoped styles do not reach overlay content. Popup, Tooltip, DropDownButton, and similar components render content in the document root. Use global (unscoped) styles for those.
8. No fabricated API: Never guess SCSS variable names, CLI option names, or ThemeBuilder property names. Use the DxDocs MCP or official docs to verify if unsure.
9. Use devextreme-cli, not devextreme-themebuilder: The CLI tool for generating themes is devextreme-cli. The correct invocation is npx -p devextreme-cli devextreme build-theme .... Do not use devextreme-themebuilder — it is a separate, older package with a different interface and different option names.
10. --output-color-scheme is NOT a color. It is the name for the output file's color scheme (e.g., pink → dx.material.pink.css). To set actual colors (accent, text, background, etc.) you MUST create a metadata JSON file with items containing SCSS token key/value pairs (e.g., "$base-accent": "#e91e63") and pass it via --input-file. See [references/themebuilder.md](references/themebuilder.md) for the full pattern.

---

Official Resources

• Predefined Themes
• ThemeBuilder UI
• ThemeBuilder CLI docs with examples
• ThemeBuilder UI guide
• HTML-Based Components Customization
• SVG-Based Components Customization
• Color Swatches

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DevExpress
• Source: DevExpress/agent-skills
• License: MIT
• Homepage: https://www.devexpress.com

Install and usage instructions live in the source repository linked above.