element-plus/docs/en-US/guide/theming.md

220 lines
6.0 KiB
Markdown
Raw Normal View History

epic(website): refactor website (#3426) * feat(website): init viteperss (#3162) * init vitepress * Finish homepage * relayout page * partial finish * update * update use lang * remove font weight; change font size * docs: optimize docs folder structure * reorganize project * fix ssr issue * fix build issues Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> * feat(website) integrate with crowdin (#3218) - Introduce Crowdin CLI - Add script for fetching Crowdin token from env - Add script for local development * fix formatting * update codeblocks (#3249) * feat(docs): update website preview script - Update azure preview build script - Eliminate dead links * bootstrap docs * fix homepage layout issue * fix formating * Finish ToC and codepen integration * reorganized files and fix issue that causes demo unavailable after build * feat(docs): migration documentations (#3283) * feat(docs): migration documentations - Move documentations to docs/ * remove unused files * docs: [popconfirm] migrate document (#3285) * feat(docs): migrate documentation from space.md to upload.md (#3292) - Upload documentations acorrodingly * docs: [date-picker] migrate document (#3289) * docs: [date-picker] migrate document * fix: typo * docs: [slider] migrate document (#3287) * docs: migrate documents (#3290) * docs: migrate-datetime-picker * docs: migrate descriptions * docs: migrate dialog * docs: migrate divider * docs: migrate drawer * docs: migrate drapdown * docs: fix drapdown * docs: migrate empty * docs: migrate form * docs: add scoped for style * docs: simplify toRefs * chore: update doc (#3297) * chore: update doc * chore: update doc * chore: update doc * feat(docs): migrate documentations from infinite-scroll to page-header (#3303) - Update docs accordingly - Update CodePen icon to match style - Update component name to match others * docs: migrate documentions (#3293) migrate list: * image * popover * scrollbar * radio * rate * skeleton * select * select-v2 * reault * progress * pagination * chore: update doc (#3305) Co-authored-by: 0song <0song@gmail.com> * Fix broken pipeline * chore: update demo plugin * website perfection * fix hydration bug * docs: update guide (#3342) * WIP docs * docs: update docs * add dark mode * make dev fetch components from local instead of node_modules Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: 三咲智子 <sxzz@sxzz.moe> * fix(docs): fix codepen code example issue (#3380) * fix(docs): fix codepen code example issue - Add lang="ts" for all example files - Fix codepen import error * revert changes in resource.vue * feat(docs): complete crowdin integration (#3408) * Update mds for preparing the integration script * deprecate old website * update sponsors and even handler for resize * update build script for preview * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * update deploy script and some bugs * Fix existing issue * chore(project): add dev preview workflow * chore(project): rename dev to staging * update the size of toc * update staging-preview script * update preview scripts * enable website build for preview * fix build error * final commitment for update the details * remove azure pipeline * move docs ignores into docs and update date Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com>
2021-09-17 00:18:50 +08:00
---
title: Theming
lang: en-US
epic(website): refactor website (#3426) * feat(website): init viteperss (#3162) * init vitepress * Finish homepage * relayout page * partial finish * update * update use lang * remove font weight; change font size * docs: optimize docs folder structure * reorganize project * fix ssr issue * fix build issues Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> * feat(website) integrate with crowdin (#3218) - Introduce Crowdin CLI - Add script for fetching Crowdin token from env - Add script for local development * fix formatting * update codeblocks (#3249) * feat(docs): update website preview script - Update azure preview build script - Eliminate dead links * bootstrap docs * fix homepage layout issue * fix formating * Finish ToC and codepen integration * reorganized files and fix issue that causes demo unavailable after build * feat(docs): migration documentations (#3283) * feat(docs): migration documentations - Move documentations to docs/ * remove unused files * docs: [popconfirm] migrate document (#3285) * feat(docs): migrate documentation from space.md to upload.md (#3292) - Upload documentations acorrodingly * docs: [date-picker] migrate document (#3289) * docs: [date-picker] migrate document * fix: typo * docs: [slider] migrate document (#3287) * docs: migrate documents (#3290) * docs: migrate-datetime-picker * docs: migrate descriptions * docs: migrate dialog * docs: migrate divider * docs: migrate drawer * docs: migrate drapdown * docs: fix drapdown * docs: migrate empty * docs: migrate form * docs: add scoped for style * docs: simplify toRefs * chore: update doc (#3297) * chore: update doc * chore: update doc * chore: update doc * feat(docs): migrate documentations from infinite-scroll to page-header (#3303) - Update docs accordingly - Update CodePen icon to match style - Update component name to match others * docs: migrate documentions (#3293) migrate list: * image * popover * scrollbar * radio * rate * skeleton * select * select-v2 * reault * progress * pagination * chore: update doc (#3305) Co-authored-by: 0song <0song@gmail.com> * Fix broken pipeline * chore: update demo plugin * website perfection * fix hydration bug * docs: update guide (#3342) * WIP docs * docs: update docs * add dark mode * make dev fetch components from local instead of node_modules Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: 三咲智子 <sxzz@sxzz.moe> * fix(docs): fix codepen code example issue (#3380) * fix(docs): fix codepen code example issue - Add lang="ts" for all example files - Fix codepen import error * revert changes in resource.vue * feat(docs): complete crowdin integration (#3408) * Update mds for preparing the integration script * deprecate old website * update sponsors and even handler for resize * update build script for preview * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * update deploy script and some bugs * Fix existing issue * chore(project): add dev preview workflow * chore(project): rename dev to staging * update the size of toc * update staging-preview script * update preview scripts * enable website build for preview * fix build error * final commitment for update the details * remove azure pipeline * move docs ignores into docs and update date Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com>
2021-09-17 00:18:50 +08:00
---
# Custom theme
epic(website): refactor website (#3426) * feat(website): init viteperss (#3162) * init vitepress * Finish homepage * relayout page * partial finish * update * update use lang * remove font weight; change font size * docs: optimize docs folder structure * reorganize project * fix ssr issue * fix build issues Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> * feat(website) integrate with crowdin (#3218) - Introduce Crowdin CLI - Add script for fetching Crowdin token from env - Add script for local development * fix formatting * update codeblocks (#3249) * feat(docs): update website preview script - Update azure preview build script - Eliminate dead links * bootstrap docs * fix homepage layout issue * fix formating * Finish ToC and codepen integration * reorganized files and fix issue that causes demo unavailable after build * feat(docs): migration documentations (#3283) * feat(docs): migration documentations - Move documentations to docs/ * remove unused files * docs: [popconfirm] migrate document (#3285) * feat(docs): migrate documentation from space.md to upload.md (#3292) - Upload documentations acorrodingly * docs: [date-picker] migrate document (#3289) * docs: [date-picker] migrate document * fix: typo * docs: [slider] migrate document (#3287) * docs: migrate documents (#3290) * docs: migrate-datetime-picker * docs: migrate descriptions * docs: migrate dialog * docs: migrate divider * docs: migrate drawer * docs: migrate drapdown * docs: fix drapdown * docs: migrate empty * docs: migrate form * docs: add scoped for style * docs: simplify toRefs * chore: update doc (#3297) * chore: update doc * chore: update doc * chore: update doc * feat(docs): migrate documentations from infinite-scroll to page-header (#3303) - Update docs accordingly - Update CodePen icon to match style - Update component name to match others * docs: migrate documentions (#3293) migrate list: * image * popover * scrollbar * radio * rate * skeleton * select * select-v2 * reault * progress * pagination * chore: update doc (#3305) Co-authored-by: 0song <0song@gmail.com> * Fix broken pipeline * chore: update demo plugin * website perfection * fix hydration bug * docs: update guide (#3342) * WIP docs * docs: update docs * add dark mode * make dev fetch components from local instead of node_modules Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: 三咲智子 <sxzz@sxzz.moe> * fix(docs): fix codepen code example issue (#3380) * fix(docs): fix codepen code example issue - Add lang="ts" for all example files - Fix codepen import error * revert changes in resource.vue * feat(docs): complete crowdin integration (#3408) * Update mds for preparing the integration script * deprecate old website * update sponsors and even handler for resize * update build script for preview * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * fix preview-build error * update deploy script and some bugs * Fix existing issue * chore(project): add dev preview workflow * chore(project): rename dev to staging * update the size of toc * update staging-preview script * update preview scripts * enable website build for preview * fix build error * final commitment for update the details * remove azure pipeline * move docs ignores into docs and update date Co-authored-by: Kevin <sxzz@sxzz.moe> Co-authored-by: zouhang <zouhang@didiglobal.com> Co-authored-by: msidolphin <msidolphin@outlook.com> Co-authored-by: Aex <spryti@qq.com> Co-authored-by: 0song <82012629+0song@users.noreply.github.com> Co-authored-by: 0song <0song@gmail.com>
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.
2022-02-08 03:54:30 +08:00
## Change theme color
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.)
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.
:::
```ts
import { createApp } 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-bg-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-bg-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/)