How to Customize Element UI Themes Using Theme-Chalk: 4 Methods Explained

You can customize Element UI themes by overriding SCSS variables in the theme-chalk package, using the element-theme CLI tool, the online Theme Roller, or configuring babel-plugin-component for on-demand styling.

Element UI, maintained by the ElemeFE organization, uses the theme-chalk package to manage its visual design system. If you need to customize Element UI themes using theme-chalk to match your brand identity, you have several compile-time and build-time options ranging from direct SCSS manipulation to visual editing tools.

What Is Theme-Chalk?

The theme-chalk package ships with Element UI and contains all component styles as SCSS source files alongside a pre-compiled CSS bundle. According to the packages/theme-chalk/README.md, you can import the compiled CSS directly for default styling, or tap into the SCSS sources for deep customization.

Key file paths in the repository include:

• packages/theme-chalk/src/index.scss – The central entry point that imports every component's styles
• packages/theme-chalk/src/common/var.scss – Where the $--* design tokens (like $--color-primary) are defined with !default flags
• packages/theme-chalk/package.json – Declares build scripts and dependencies for the theme package

Method 1: SCSS Variable Override (Compile-Time)

The most flexible way to customize Element UI themes using theme-chalk is to override SCSS variables before importing the framework's styles. This method requires a SCSS pipeline in your build tool (Webpack, Vite, etc.).

Creating Your Variables File

Create a file named element-variables.scss in your project root. Override any $--* token before importing the theme-chalk source:

/* element-variables.scss */
$--color-primary: #ff5722;           // Change primary brand color
$--border-radius-base: 4px;          // Adjust global border radius
$--font-path: '~element-ui/lib/theme-chalk/fonts';  // Required for icon fonts

@import "~element-ui/packages/theme-chalk/src/index";

The $--font-path variable is critical because the default CSS uses relative url() paths for icon fonts. When compiling SCSS yourself, you must point this to the actual font directory inside node_modules/element-ui/lib/theme-chalk/fonts.

Importing in Your Application

Replace the default CSS import in your entry file (e.g., main.js) with your custom SCSS file:

import Vue from 'vue';
import Element from 'element-ui';
import './element-variables.scss';  // Custom theme overrides

Vue.use(Element);

This approach processes your overrides at build time, producing a lean CSS bundle containing only your customized values.

Method 2: CLI Theme Tool (Element-Theme)

If you prefer not to set up a SCSS pipeline, use the element-theme CLI tool to generate a custom CSS bundle. This method is documented in examples/docs/en-US/custom-theme.md.

Installation and Setup

Install the theme generator and the raw SCSS source package:

npm install element-theme --save-dev
npm install element-theme-chalk --save-dev

Generate the variables file:

npx et -i

This creates element-variables.scss in your project root containing all available $--* tokens.

Building the Custom Theme

Edit element-variables.scss to change design tokens, then compile:

npx et

# Or with watch mode and custom output:

npx et -w -o ./src/theme

This outputs a theme/ folder containing index.css and font files. Import this compiled CSS instead of the default Element UI styles:

import '../theme/index.css';
import ElementUI from 'element-ui';
import Vue from 'vue';

Vue.use(ElementUI);

Method 3: Online Theme Roller

For visual customization without touching code, use the Theme Roller web application linked from the Element UI documentation.

1. Open the Theme Roller in your browser.
2. Adjust global tokens (primary color, border radius, font sizes) and preview changes in real-time.
3. Click Download to receive a ZIP archive containing theme/index.css.
4. Extract and import the CSS file into your project as shown in Method 2.

This approach is ideal for designers or rapid prototyping when you don't need version-controlled theme source files.

Method 4: On-Demand Component Theming

When using babel-plugin-component to import only specific Element UI components, you must configure the plugin to point to your custom theme directory instead of the default theme-chalk.

Update your .babelrc or babel.config.js:

{
  "plugins": [
    [
      "component",
      {
        "libraryName": "element-ui",
        "styleLibraryName": "~theme"
      }
    ]
  ]
}

The ~theme value points to a ./theme folder relative to your project root (created via Method 2 or 3). Now when you import individual components:

import { Button, Select } from 'element-ui';

Babel will automatically import theme/button.css and theme/select.css instead of the default theme-chalk versions, ensuring your custom tokens apply to on-demand imports.

Summary

• Theme-chalk is the official SCSS-based styling package for Element UI, located at packages/theme-chalk/ in the ElemeFE/element repository.
• SCSS variable override offers maximum flexibility by redefining $--* tokens before importing packages/theme-chalk/src/index.scss, but requires a build-time SCSS pipeline.
• Element-theme CLI generates static CSS bundles without requiring SCSS knowledge; use et -i to scaffold variables and et to compile.
• Theme Roller provides a visual interface for non-developers to generate custom CSS packages.
• Babel-plugin-component integration requires setting styleLibraryName to your custom theme path to ensure on-demand imports use overridden styles.

Frequently Asked Questions

What is the difference between theme-chalk and element-theme?

Theme-chalk is the core SCSS source package containing Element UI's design tokens and component styles, located in packages/theme-chalk/. Element-theme is a CLI tool that consumes theme-chalk's variables to generate compiled CSS bundles without requiring you to set up a SCSS build pipeline in your own project.

How do I change the primary color in Element UI?

To change the primary color, override the $--color-primary SCSS variable before importing theme-chalk. Create a file with $--color-primary: #yourColor; followed by @import "~element-ui/packages/theme-chalk/src/index";. Alternatively, use the CLI tool (et -i) to generate a variables file, change the primary color value, and run et to build the custom CSS.

Can I use custom themes with babel-plugin-component?

Yes, but you must configure the styleLibraryName option in your Babel configuration to point to your custom theme directory instead of the default theme-chalk. Set "styleLibraryName": "~theme" (or your custom path) so that when you import individual components on-demand, Babel pulls the CSS from your customized theme folder rather than the default package.

Where are the SCSS variables defined in the Element UI source code?

The SCSS design tokens (variables prefixed with $--) are defined in packages/theme-chalk/src/common/var.scss. This file sets default values using the !default flag, which allows your custom variables to override them when imported beforehand. The main entry point packages/theme-chalk/src/index.scss imports these variables along with all component-specific styles.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}