• 中文简体
• English

This documentation will list breaking changes with Element UI 2.x.

Dev Environment

Vue CLI

If you use Vue CLI as your build tool, please upgrade to latest version, both v4 and v5 are acceptable.

Webpack 4

If you use Webpack 4 as your build tool, please consider the code below.

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.mjs', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.mjs$/i,
        include: /node_modules/,
        type: 'javascript/auto',
      },
    ],
  },
}

Webpack 5

If you use Webpack 5 as your build tool, please consider the code below.

// webpack.config.js
module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.mjs', '.json'],
  },
  module: {
    rules: [
      {
        test: /\.mjs$/i,
        resolve: { byDependency: { esm: { fullySpecified: false } } },
      },
    ],
  },
}

Compatibility

The table below shows the minimum browser requirements for Element Plus.

Edge ≥ 79	Firefox ≥ 78	Chrome ≥ 64	Safari ≥ 12

If you want to use Element Plus normally on lower version browsers, please manually use Babel, ESBuild or other transform tools and import corresponding polyfills.

It is worth noting that Element Plus uses ResizeObserver, you need to import resize-observer-polyfill. For details, see ResizeObserver Compatibility. Please refer to the documentation for more details.

Font Icon Removed

Class name based Font Icon has been removed, which means you need to migrate all el-icon- related code to SVG Font, and please refer to the comparison table below. For more details about SVG icons, you can refer to documentation. You can also use the unplugin-icons plugin for automatic import.

Element UI

<template>
  <el-button type="primary" icon="el-icon-search">Search</el-button>
</template>

Element Plus

<script setup lang="ts">
import { Search } from '@element-plus/icons'
</script>

<template>
  <el-button type="primary" :icon="Search">Search</el-button>
</template>

Release Package

The source code /packages of Element Plus has been removed in the npm release package. If you need, please copy the source code yourself.

Install

Import

The import path of Element Plus is different from that of Element UI. Please consider the code below. For more methods, please refer to Installation Documentation

import ElementPlus from 'element-plus'
import 'element-plus/theme-chalk/index.css'

// If you need to import the SCSS version, please use the following code (please use the latest version of Sass)
// import 'element-plus/theme-chalk/src/index.scss'

Global Configuration

Global configuration Vue.prototype.$ELEMENT has been removed, please consider the code below.

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import App from './App.vue'

createApp(App)
  .use(ElementPlus, {
    // options
  })
  .mount('#app')

Or use config-provider component, please consider the code below.

<template>
  <el-config-provider :size="small">
    <el-button>Button</el-button>
  </el-config-provider>
</template>

Design

The component size system is switched from default / medium / small / mini to large / default / small. default will be the default size, use large if you need to increase it, or use small to reduce the size. In terms of Padding, it is optimized to a more general 4px system, using 4/8 px as the atomic unit to control the padding consistency of the entire system. That is, the padding of large components is also large, and the padding of small components is also small.

The main components involved are Button, Radio, Checkbox, Input, Select, DatePicker, Form, Table, Tag, and other components with size properties.
It mainly involves attributes such as padding and margin attribute modification, font-size and other font and icon size modification, etc.

Custom Theme

If you are only using compiled CSS and have no variable customization requirements, you do not need to read the following.

Sass

The Sass team discourages the continued use of the @import rule. Sass will gradually phase it out over the next few years, and eventually remove it from the language entirely. Prefer the @use rule instead. (Note that only Dart Sass currently supports @use. Users of other implementations must use the @import rule instead.) Sass Documentation

In the .scss file, import all styles:

@use 'element-plus/theme-chalk/src/index.scss' as *;

Due to the scope of @use, when using a variable, you need to export it, or forward the variable through @forward. For example:

@use "'element-plus/theme-chalk/src/common/var.scss'" as *;

'\*' means no namespace, it can also be named.

@use "'element-plus/theme-chalk/src/common/var.scss'" as vars;
vars.xxx

Forward app variables via the @forward syntax:

@forward https://sass-lang.com/documentation/at-rules/forward

Variable

• -background-color -> -bg-color
• -font-color -> -text-color

The variable name naming will be similar to the variable naming in tailwindcss.

The variables of each component are organized using @use 'sass:map';, and the variables of the corresponding component are moved to the corresponding component name.

See element-plus/theme-chalk/src/common/var.scss for exposed variables.

For example, the default variable for the switch component is:

$switch: () !default;
$switch: map.merge(
  (
    'on-color': var(--el-color-primary),
    'off-color': var(--el-border-color-base),
    'core-border-radius': 10px,
    'width': 40px,
    'height': 20px,
    'button-size': 16px,
  ),
  $switch
);

User-defined variables: (will automatically override and merge default variables)

@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  // set theme color
  $colors:
    (
      'primary': (
        'base': green,
      )
    ),
  // override switch component variable
  $switch: ('height': 40px)
);

For more details, please refer to Custom theme.

Internationalization

Element Plus uses English as the default language. To change the default language, please refer to the Global Configuration section and set the locale property.

For more details, please refer to documentation.

Component

Since Vue 3 changed the property name of v-model from value to model-value, if you use the value property, please change it to model-value (v-model no special The description does not need to be modified), and will not be repeated later.

Layout

Row

Dialog

Menu

Popconfirm

Timeline

Date Picker / Time Picker / DateTime Picker

Tooltip

Calendar

Popover

Scrollbar

Form

float layout has been changed to flex layout.

For more details about features and breaking changes, please see this (in Chinese)

Templates

The following is a quick start template, I believe it will help you.

• element-plus-vite-starter - A starter kit for Element Plus with Vite.
• element-plus-webpack5-starter - A starter kit for Element Plus with Webpack 5.
• element-plus-webpack4-starter - A starter kit for Element Plus with Webpack 4.