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

> Customize Element UI themes using theme-chalk with 4 methods: SCSS variables, CLI tool, Theme Roller, or babel-plugin-component. Style your UI efficiently.

- Repository: [饿了么前端/element](https://github.com/ElemeFE/element)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/packages/theme-chalk/src/index.scss) – The central entry point that imports every component's styles
- [`packages/theme-chalk/src/common/var.scss`](https://github.com/ElemeFE/element/blob/main/packages/theme-chalk/src/common/var.scss) – Where the `$--*` design tokens (like `$--color-primary`) are defined with `!default` flags
- [`packages/theme-chalk/package.json`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/element-variables.scss) in your project root. Override any `$--*` token before importing the theme-chalk source:

```scss
/* 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`](https://github.com/ElemeFE/element/blob/main/main.js)) with your custom SCSS file:

```javascript
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`](https://github.com/ElemeFE/element/blob/main/examples/docs/en-US/custom-theme.md).

### Installation and Setup

Install the theme generator and the raw SCSS source package:

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

```

Generate the variables file:

```bash
npx et -i

```

This creates [`element-variables.scss`](https://github.com/ElemeFE/element/blob/main/element-variables.scss) in your project root containing all available `$--*` tokens.

### Building the Custom Theme

Edit [`element-variables.scss`](https://github.com/ElemeFE/element/blob/main/element-variables.scss) to change design tokens, then compile:

```bash
npx et

# Or with watch mode and custom output:

npx et -w -o ./src/theme

```

This outputs a `theme/` folder containing [`index.css`](https://github.com/ElemeFE/element/blob/main/index.css) and font files. Import this compiled CSS instead of the default Element UI styles:

```javascript
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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/babel.config.js):

```json
{
  "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:

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

```

Babel will automatically import [`theme/button.css`](https://github.com/ElemeFE/element/blob/main/theme/button.css) and [`theme/select.css`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/packages/theme-chalk/src/index.scss) imports these variables along with all component-specific styles.