2021-09-17 00:18:50 +08:00
---
title: Theming
2021-10-22 19:32:39 +08:00
lang: en-US
2021-09-17 00:18:50 +08:00
---
2021-04-21 14:08:00 +08:00
2021-09-19 17:25:49 +08:00
# Custom theme
2020-08-13 15:18:26 +08:00
2021-09-17 00:18:50 +08:00
Element Plus uses BEM-styled CSS so that you can override styles easily. But if
you need to replace styles at a large scale, e.g. change the theme color from
blue to orange or green, maybe overriding them one by one is not a good idea. We
provide four ways to change the style variables.
2021-04-21 14:08:00 +08:00
2022-02-08 03:54:30 +08:00
## Change theme color
2021-09-19 17:25:49 +08:00
2021-09-29 09:13:12 +08:00
These are examples about custom theme.
- Full import: [element-plus-vite-starter ](https://github.com/element-plus/element-plus-vite-starter )
- On demand: [unplugin-element-plus/examples/vite ](https://github.com/element-plus/unplugin-element-plus )
2021-09-27 01:15:08 +08:00
2021-09-19 17:25:49 +08:00
### By SCSS variables
`theme-chalk` is written in SCSS.
You can find SCSS variables in [`packages/theme-chalk/src/common/var.scss` ](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss ).
::: warning
2021-09-20 00:04:11 +08:00
2021-09-28 20:42:12 +08:00
We use sass modules ([sass:map](https://sass-lang.com/documentation/values/maps)...) to refactor all SCSS variables.
2021-09-19 17:25:49 +08:00
2021-09-28 20:42:12 +08:00
> [Introducing Sass Modules | CSS-TRICKS](https://css-tricks.com/introducing-sass-modules/)
2021-09-19 17:25:49 +08:00
2021-09-28 20:42:12 +08:00
For example, We use `$colors` as a map to preserve different types of colors.
`$notification` is a map where all variables of the `notification` component at.
2021-09-19 17:25:49 +08:00
In the future, we will write documentation for variables that can be customized for each component. You can also directly checkout the source [var.scss ](https://github.com/element-plus/element-plus/blob/dev/packages/theme-chalk/src/common/var.scss ).
2021-09-20 00:04:11 +08:00
2021-09-19 17:25:49 +08:00
:::
```scss
2021-09-28 20:42:12 +08:00
$colors: () !default;
$colors: map.deep-merge(
2021-09-19 17:25:49 +08:00
(
'white': #ffffff ,
'black': #000000 ,
'primary': (
'base': #409eff ,
),
'success': (
'base': #67c23a ,
),
'warning': (
'base': #e6a23c ,
),
'danger': (
'base': #f56c6c ,
),
'error': (
'base': #f56c6c ,
),
'info': (
'base': #909399 ,
),
),
2021-11-19 20:22:16 +08:00
$colors
2021-09-19 17:25:49 +08:00
);
```
2021-09-20 00:04:11 +08:00
### How to override it?
2021-09-19 17:25:49 +08:00
2021-09-28 20:42:12 +08:00
If your project also uses SCSS, you can directly change Element Plus style variables. Create a new style file, e.g. `styles/element/index.scss` :
2021-09-20 00:04:11 +08:00
2021-09-19 17:25:49 +08:00
```scss
2021-09-28 20:42:12 +08:00
// styles/element/index.scss
2021-09-19 17:25:49 +08:00
/* just override what you need */
2021-11-28 20:20:09 +08:00
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
2021-09-28 20:42:12 +08:00
$colors: (
2021-11-28 20:20:09 +08:00
'primary': (
'base': green,
2021-09-28 20:42:12 +08:00
),
2021-11-28 20:20:09 +08:00
)
2021-09-19 17:25:49 +08:00
);
2021-09-28 20:42:12 +08:00
2021-11-02 14:13:04 +08:00
// If you just import on demand, you can ignore the following content.
// if you want to import all styles:
// @use "element-plus/theme-chalk/src/index.scss" as *;
2021-09-19 17:25:49 +08:00
```
2021-09-28 20:42:12 +08:00
Then in the entry file of your project, import this style file instead of Element's built CSS:
2021-09-19 17:25:49 +08:00
2021-09-20 00:04:11 +08:00
::: tip
2021-09-28 20:42:12 +08:00
Import `element/index.scss` before scss of element-plus to avoid the problem of sass mixed variables, because we need generate light-x by your custom variables.
2021-09-20 00:04:11 +08:00
:::
2021-09-27 01:15:08 +08:00
Create a `element/index.scss` to combine your variables and variables of element-plus. (If you import them in ts, they will not be combined.)
2021-09-27 22:02:19 +08:00
::: tip
In addition, you should distinguish your scss from the element variable scss.
If they are mixed together, each hot update of `element-plus` needs to compile a large number of scss files, resulting in slow speed.
:::
2021-09-27 01:15:08 +08:00
2021-09-19 17:25:49 +08:00
```ts
2022-03-08 14:03:32 +08:00
import { createApp } from 'vue'
2021-09-27 01:15:08 +08:00
import './styles/element/index.scss'
2021-09-19 17:25:49 +08:00
import ElementPlus from 'element-plus'
import App from './App.vue'
const app = createApp(App)
app.use(ElementPlus)
```
2021-09-28 20:42:12 +08:00
If you are using vite, and you want to custom theme when importing on demand.
2021-11-02 14:13:04 +08:00
Use `scss.additionalData` to compile variables with scss of every component.
2021-09-28 20:42:12 +08:00
```ts
import path from 'path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
2021-11-02 14:13:04 +08:00
// You can also use unplugin-vue-components
// import Components from 'unplugin-vue-components/vite'
// import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
2021-09-28 20:42:12 +08:00
2021-11-02 14:13:04 +08:00
// or use unplugin-element-plus
2021-09-28 20:42:12 +08:00
import ElementPlus from 'unplugin-element-plus/vite'
// vite.config.ts
export default defineConfig({
resolve: {
alias: {
'~/': `${path.resolve(__dirname, 'src')}/` ,
},
},
css: {
preprocessorOptions: {
scss: {
additionalData: `@use "~/styles/element/index.scss" as *;` ,
},
},
},
plugins: [
vue(),
2021-11-02 14:13:04 +08:00
// use unplugin-vue-components
// Components({
// resolvers: [
// ElementPlusResolver({
// importStyle: "sass",
// // directives: true,
// // version: "1.2.0-beta.1",
// }),
// ],
// }),
// or use unplugin-element-plus
2021-09-28 20:42:12 +08:00
ElementPlus({
useSource: true,
}),
],
})
```
2021-09-19 17:25:49 +08:00
### By CSS Variable
CSS Variables is a very useful feature, already supported by almost all browsers. (IE: Wait?)
> Learn more from [Using CSS custom properties (variables) | MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
We have used css variables to reconstruct the style system of almost all components. (Since `1.0.2-beta-70` [#2242 ](https://github.com/element-plus/element-plus/issues/2242 ))
::: tip
2021-09-20 00:04:11 +08:00
2021-09-19 17:25:49 +08:00
It is compatible with the SCSS variable system. We use the function of SCSS to automatically generate css variables for use.
2021-09-20 00:04:11 +08:00
2021-09-19 17:25:49 +08:00
:::
This means you can dynamically change individual variables inside the component to better customize it without having to modify scss and recompile it.
> In the future, the css variable names and role documentation for each component will be written to each component.
Like this:
```css
:root {
--el-color-primary: green;
}
```
If you just want to customize a particular component, just add inline styles for certain components individually.
```html
2021-11-22 11:19:44 +08:00
< el-tag style = "--el-tag-bg-color: red" > Tag< / el-tag >
2021-09-19 17:25:49 +08:00
```
For performance reasons, it is more recommended to custom css variables under a class rather than the global `:root` .
```css
.custom-class {
2021-11-22 11:19:44 +08:00
--el-tag-bg-color: red;
2021-09-19 17:25:49 +08:00
}
```
If you want to control css var by script, try this:
```ts
// document.documentElement is global
const el = document.documentElement
// const el = document.getElementById('xxx')
// get css var
getComputedStyle(el).getPropertyValue(`--el-color-primary`)
// set css var
el.style['--el-color-primary'] = 'red'
```
If you want a more elegant way, check this out.
[useCssVar | VueUse ](https://vueuse.org/core/usecssvar/ )