mirror of
https://gitee.com/element-plus/element-plus.git
synced 2024-12-16 02:11:48 +08:00
4c4666d65a
* docs(docs): fix custom theme doc fix #4148 * docs(docs): add on-demand import use, compatible with full use
391 lines
11 KiB
Markdown
391 lines
11 KiB
Markdown
---
|
|
title: Theming
|
|
lang: en-US
|
|
---
|
|
|
|
# Custom theme
|
|
|
|
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.
|
|
|
|
## Change theme color <el-tag type="success" style="vertical-align: middle;">since 1.1.0-beta.1</el-tag>
|
|
|
|
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)
|
|
|
|
### 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
|
|
|
|
We use sass modules ([sass:map](https://sass-lang.com/documentation/values/maps)...) to refactor all SCSS variables.
|
|
|
|
> [Introducing Sass Modules | CSS-TRICKS](https://css-tricks.com/introducing-sass-modules/)
|
|
|
|
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.
|
|
|
|
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).
|
|
|
|
:::
|
|
|
|
```scss
|
|
$colors: () !default;
|
|
$colors: map.deep-merge(
|
|
(
|
|
'white': #ffffff,
|
|
'black': #000000,
|
|
'primary': (
|
|
'base': #409eff,
|
|
),
|
|
'success': (
|
|
'base': #67c23a,
|
|
),
|
|
'warning': (
|
|
'base': #e6a23c,
|
|
),
|
|
'danger': (
|
|
'base': #f56c6c,
|
|
),
|
|
'error': (
|
|
'base': #f56c6c,
|
|
),
|
|
'info': (
|
|
'base': #909399,
|
|
),
|
|
),
|
|
$--colors
|
|
);
|
|
```
|
|
|
|
### How to override it?
|
|
|
|
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`:
|
|
|
|
```scss
|
|
// styles/element/index.scss
|
|
/* just override what you need */
|
|
@forward "element-plus/theme-chalk/src/common/var.scss" with (
|
|
$colors: (
|
|
"primary": (
|
|
"base": green,
|
|
),
|
|
),
|
|
);
|
|
|
|
// 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 *;
|
|
```
|
|
|
|
Then in the entry file of your project, import this style file instead of Element's built CSS:
|
|
|
|
::: tip
|
|
|
|
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.
|
|
|
|
:::
|
|
|
|
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.)
|
|
|
|
::: 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.
|
|
|
|
:::
|
|
|
|
```ts
|
|
import Vue from 'vue'
|
|
|
|
import './styles/element/index.scss'
|
|
import ElementPlus from 'element-plus'
|
|
import App from './App.vue'
|
|
|
|
const app = createApp(App)
|
|
app.use(ElementPlus)
|
|
```
|
|
|
|
If you are using vite, and you want to custom theme when importing on demand.
|
|
|
|
Use `scss.additionalData` to compile variables with scss of every component.
|
|
|
|
```ts
|
|
import path from 'path'
|
|
import { defineConfig } from 'vite'
|
|
import vue from '@vitejs/plugin-vue'
|
|
// You can also use unplugin-vue-components
|
|
// import Components from 'unplugin-vue-components/vite'
|
|
// import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
|
|
|
|
// or use unplugin-element-plus
|
|
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(),
|
|
// use unplugin-vue-components
|
|
// Components({
|
|
// resolvers: [
|
|
// ElementPlusResolver({
|
|
// importStyle: "sass",
|
|
// // directives: true,
|
|
// // version: "1.2.0-beta.1",
|
|
// }),
|
|
// ],
|
|
// }),
|
|
// or use unplugin-element-plus
|
|
ElementPlus({
|
|
useSource: true,
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
### 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
|
|
|
|
It is compatible with the SCSS variable system. We use the function of SCSS to automatically generate css variables for use.
|
|
|
|
:::
|
|
|
|
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
|
|
<el-tag style="--el-tag-background-color: red">Tag</el-tag>
|
|
```
|
|
|
|
For performance reasons, it is more recommended to custom css variables under a class rather than the global `:root`.
|
|
|
|
```css
|
|
.custom-class {
|
|
--el-tag-background-color: red;
|
|
}
|
|
```
|
|
|
|
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/)
|
|
|
|
## Change theme color <el-tag type="error" style="vertical-align: middle;">Deprecated since 1.1.0-beta.1</el-tag>
|
|
|
|
If you just want to change the theme color of Element Plus, the
|
|
[theme preview website](https://element-plus.github.io/theme-chalk-preview/#/en-US)
|
|
is recommended.
|
|
The theme color of Element Plus is bright and friendly blue. By changing it, you
|
|
can make Element Plus more visually connected to specific projects.
|
|
|
|
The above website enables you to preview theme of a new theme color in real-time,
|
|
and it can generate a complete style package based on the new theme color for you
|
|
to download directly (to import new style files in your project, please refer to
|
|
the 'Import custom theme' or 'Import component theme on demand' part of this section).
|
|
|
|
### Update SCSS variables in your project
|
|
|
|
`theme-chalk` is written in SCSS. If your project also uses SCSS, you can directly
|
|
change Element Plus style variables. Create a new style file, e.g. `element-variables.scss`:
|
|
|
|
```scss
|
|
/* theme color */
|
|
$--color-primary: teal; /* icon font path, required */
|
|
$--font-path: '~element-plus/lib/theme-chalk/fonts';
|
|
@use '~element-plus/packages/theme-chalk/src/index';
|
|
```
|
|
|
|
Then in the entry file of your project, import this style file instead of Element's
|
|
built CSS:
|
|
|
|
```ts
|
|
import Vue from 'vue'
|
|
import ElementPlus from 'element-plus'
|
|
import './element-variables.scss'
|
|
import App from './App.vue'
|
|
|
|
const app = createApp(App)
|
|
app.use(ElementPlus)
|
|
```
|
|
|
|
:::tip
|
|
|
|
Note that it is required to override icon font path to the relative path of
|
|
Element's font files.
|
|
|
|
:::
|
|
|
|
### CLI theme tool
|
|
|
|
If you project doesn't use SCSS, you can customize themes with our CLI theme tool:
|
|
|
|
#### Installation
|
|
|
|
First install the theme generator globally or locally. Local install is
|
|
recommended because in this way, when others clone your project, npm will
|
|
automatically install it for them.
|
|
|
|
```shell
|
|
npm i element-theme -g
|
|
```
|
|
|
|
Then install the chalk theme from npm or GitHub.
|
|
|
|
```shell
|
|
# from npm
|
|
npm i element-theme-chalk -D
|
|
|
|
# from GitHub
|
|
npm i https://github.com/ElementUI/theme-chalk -D
|
|
```
|
|
|
|
#### Initialize variable file
|
|
|
|
After successfully installing the above packages, a command named `et` is
|
|
available in CLI (if the packages are installed locally, use `node_modules/.bin/et`
|
|
instead).
|
|
Run `-i` to initialize the variable file which outputs to `element-variables.scss`
|
|
by default. And you can specify its output directory as you will.
|
|
|
|
```shell
|
|
et -i [custom output file]
|
|
|
|
> ✅ Generator variables file
|
|
```
|
|
|
|
In `element-variables.scss` you can find all the variables we used to style
|
|
Element Plus and they are defined in SCSS format. Here's a snippet:
|
|
|
|
```css
|
|
$--color-primary: #409EFF !default;
|
|
$--color-primary-light-1: mix($--color-white, $--color-primary, 10%) !default; /* 53a8ff */
|
|
$--color-primary-light-2: mix($--color-white, $--color-primary, 20%) !default; /* 66b1ff */
|
|
$--color-primary-light-3: mix($--color-white, $--color-primary, 30%) !default; /* 79bbff */
|
|
$--color-primary-light-4: mix($--color-white, $--color-primary, 40%) !default; /* 8cc5ff */
|
|
$--color-primary-light-5: mix($--color-white, $--color-primary, 50%) !default; /* a0cfff */
|
|
$--color-primary-light-6: mix($--color-white, $--color-primary, 60%) !default; /* b3d8ff */
|
|
$--color-primary-light-7: mix($--color-white, $--color-primary, 70%) !default; /* c6e2ff */
|
|
$--color-primary-light-8: mix($--color-white, $--color-primary, 80%) !default; /* d9ecff */
|
|
$--color-primary-light-9: mix($--color-white, $--color-primary, 90%) !default; /* ecf5ff */
|
|
|
|
$--color-success: #67c23a !default;
|
|
$--color-warning: #e6a23c !default;
|
|
$--color-danger: #f56c6c !default;
|
|
$--color-info: #909399 !default;
|
|
|
|
...
|
|
```
|
|
|
|
#### Modify variables
|
|
|
|
Just edit `element-variables.scss`, e.g. changing the theme color to red:
|
|
|
|
```CSS
|
|
$--color-primary: red;
|
|
```
|
|
|
|
#### Build theme
|
|
|
|
After saving the variable file, use `et` to build your theme. You can activate
|
|
`watch` mode by adding a parameter `-w`. And if you customized the variable
|
|
file's output, you need to add a parameter `-c` and variable file's name. By
|
|
default the build theme file is placed inside `./theme`. You can specify its
|
|
output directory with parameter `-o`.
|
|
|
|
```shell
|
|
et
|
|
|
|
> ✅ build theme font
|
|
> ✅ build element theme
|
|
```
|
|
|
|
### Use custom theme
|
|
|
|
We will cover how to use your customized theme in your project in this section
|
|
|
|
#### Import custom theme
|
|
|
|
Importing your own theme is just like importing the default theme, only
|
|
this time you import the file built from "Online Theme Roller" or "CLI tool":
|
|
|
|
```javascript
|
|
import { createApp } from 'vue'
|
|
import '../theme/index.css'
|
|
import ElementPlus from 'element-plus'
|
|
|
|
createApp(App).use(ElementPlus)
|
|
```
|
|
|
|
#### Import component theme on demand
|
|
|
|
If you are using `babel-plugin-component` for on-demand import, just modify
|
|
`.babelrc` and specify `styleLibraryName` to the path where your custom theme
|
|
is located relative to `.babelrc`. Note that `~` is required:
|
|
|
|
```json
|
|
{
|
|
"plugins": [
|
|
[
|
|
"component",
|
|
{
|
|
"libraryName": "element-plus",
|
|
"styleLibraryName": "~theme"
|
|
}
|
|
]
|
|
]
|
|
}
|
|
```
|
|
|
|
If you are unfamiliar with `babel-plugin-component`, please refer to [Quick Start](/en-US/guide/quickstart.html).
|
|
For more details, check out the [project repository](https://github.com/ElementUI/element-theme)
|
|
of `element-theme`.
|