Element Plus Breaking Changes (English version)

[sxzz]

• 中文简体
• 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>

Component Name	Old Name (Type)	New Name (Type)
Avatar	icon (string)	icon (string / Component)
Button	icon (string)	icon (string / Component)
DatePicker	prefix-icon (string)	prefix-icon (string / Component)
DatePicker	clear-icon (string)	clear-icon (string / Component)
Input	prefix-icon (string)	prefix-icon (string / Component)
Input	suffix-icon (string)	suffix-icon (string / Component)
MessageBox	icon-class (string)	icon (string / Component)
Message	icon-class (string)	icon (string / Component)
Notification	icon-class (string)	icon (string / Component)
PageHeader	icon (string)	icon (string / Component)
Select	clear-icon (string)	clear-icon (string / Component)
Select V2	clear-icon (string)	clear-icon (string / Component)
TimePicker	prefix-icon (string)	prefix-icon (string / Component)
TimePicker	clear-icon (string)	clear-icon (string / Component)
TimeSelect	prefix-icon (string)	prefix-icon (string / Component)
TimeSelect	clear-icon (string)	clear-icon (string / Component)
Timeline	icon (string)	icon (string / Component)
Tree	icon-class (string)	icon (string / Component)

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

Category	Old Name	New Name	Description
property	type	removed	Support flex layout only

Dialog

Category	Old Name	New Name	Description
property	visible	model-value / v-model	-

Menu

Category	Old Name	New Name	Description
component name	ElSubmenu / el-submenu	ElSubMenu / el-sub-menu	-

Popconfirm

Category	Old Name	New Name	Description
event	on-confirm	confirm	Only when Element UI version is lower than 2.14.0
event	on-cancel	cancel	Only when Element UI version is lower than 2.14.0

Timeline

Category	Old Name	New Name	Description
property	reverse	removed	reverse the array by yourself

Date Picker / Time Picker / DateTime Picker

Category	Old Name	New Name	Description
property	picker-options	removed	this property has been moved to the top level
property	picker-options.format	removed	use top-level prop format
property	picker-options.selectableRange	disabled-hours / disabled-minutes / disabled-seconds	See documentation for more details
property	first-day-of-week	removed	use the locale of dayjs instead.
property	default-time	-	only Date objects are supported

Tooltip

Category	Old Name	New Name	Description
property	popper-options	-	Since we have upgraded the popperjs version to v2, this property is completely different from v1. See popperjs documentation.
property	offset	-	default value changed from 0 to 12
property	open-delay	show-after	-
property	close-delay	hide-after	-
property	hide-after	auto-close	-

Calendar

Category	Old Name	New Name	Description
property	value	model-value / v-model	object only
property	range	-	object only, do not have to be start day of week / end day of week
property	first-day-of-week	removed	use Day.js locale instead

Popover

Category	Old Name	New Name	Description
property	open-delay	show-after	-
property	close-delay	hide-after	-
property	hide-after	auto-close	-

Scrollbar

Category	Old Name	New Name	Description
ref	wrap	wrap$	-

Form

float layout has been changed to flex layout.

Category	Old Name	New Name	Description
method	validate	-	When validation failure, return a Promise of reject, no longer false

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.

[jw-foss]

Thank you for making this list 😃

[orenmizr]

hi, there has been talk regarding the theming of the ui... light/dark and also making the style next to the component.
is this version without these changes ?

i wish there was a template for changing the theme and style elements via the sass... it was not trivial... tryed changing the grid and stopped mid dev since it was too much effort... some stuff remained light while others got styled :(

[volarname]

i am also interested in dark/light theme switch
also icon component to support additional icon packs like mdi

[sxzz]

Dark theme is in development. Please refer to #3754

[candisecandise]

if i still use element-plus-v1-beta，where can i find the document？now the document on the official webside is about v2，and i can switch the version~

[sxzz]

Most the same thing. You can find here https://github.com/element-plus/element-plus/commits/gh-pages by date.

[candisecandise]

It seems like I need to download the code for the corresponding date and run it，then I can see the website for the corresponding date?

[sxzz]

Yes, please refer to #7230

[candisecandise]

And I found another simpler method, element-plus v1 is almost based on element, so I can go to element website for reference~

[sxzz]

Yeah