Element Plus

2.13.7 · active · verified Sun Apr 19

Element Plus is a comprehensive UI component library for Vue 3, built entirely with the Composition API and TypeScript. It offers a rich set of customizable components designed to streamline development of web applications. The library is currently at version 2.13.7 and maintains a frequent release cadence, often releasing multiple patch versions per month to address bugs and introduce minor features, with occasional minor versions for larger feature sets. Key differentiators include its strong TypeScript support, native Vue 3 reactivity, and an extensive ecosystem of tools and documentation, making it a robust alternative to older Vue 2 UI libraries like Element UI.

Common errors

```
[Vue warn]: Failed to resolve component: ElButton
```
cause Element Plus components are not properly registered with the Vue application or the component using them.

fix Ensure you have called `app.use(ElementPlus);` in your main application entry file (e.g., `main.ts` or `main.js`). If using individual components without global registration, ensure they are imported and registered locally in your Vue component's `<script setup>` or `components` option.
```
TypeError: Cannot read properties of undefined (reading 'use') at main.js:X:Y
```
cause This typically occurs when trying to use CommonJS `require()` syntax (e.g., `const ElementPlus = require('element-plus');`) in a modern Vue 3 project which expects ES Module imports.

fix Replace `const ElementPlus = require('element-plus');` with `import ElementPlus from 'element-plus';` in your entry file.
```
Element Plus components appear unstyled or with only basic browser styling.
```
cause The main stylesheet for Element Plus has not been imported into your project.

fix Add `import 'element-plus/dist/index.css';` to your main application entry file (e.g., `main.ts` or `main.js`).

Warnings

breaking Migrating from Element UI (Vue 2) to Element Plus (Vue 3) involves significant breaking changes due to the underlying Vue version upgrade and API redesign. A dedicated migration tool and detailed breaking change list are available.
Fix: Refer to the official 'Breaking Change List' discussion on GitHub and consider using the 'gogocode migration tool' to assist with project migration from Element UI to Element Plus.
gotcha Element Plus requires Node.js version 20 or higher for development environments. Older Node.js versions may lead to build errors or unexpected behavior.
Fix: Ensure your Node.js environment is updated to version 20 or later. Use a Node.js version manager like `nvm` to easily switch between versions (`nvm install 20 && nvm use 20`).
gotcha Starting with version 2.13.0, Element Plus officially supports and recommends Vue 3.5. While it might work with older Vue 3 versions (>=3.3.0), using Vue 3.5 ensures full compatibility and access to the latest features and optimizations.
Fix: Upgrade your project's Vue dependency to `^3.5.0` to ensure optimal compatibility with Element Plus versions 2.13.0 and newer. Update your `package.json` and run `npm install` or `yarn install`.

Install

npm install element-plus npm
yarn add element-plus yarn
pnpm add element-plus pnpm

Imports

ElementPlus (global install)
wrong:
```
const ElementPlus = require('element-plus');
```
correct:
```
import ElementPlus from 'element-plus';
```
For global registration with `app.use(ElementPlus);`. Element Plus is ESM-first and not designed for CommonJS `require` in modern Vue 3 setups.
ElButton (specific component)
wrong:
```
import ElButton from 'element-plus/lib/ElButton';
```
correct:
```
import { ElButton } from 'element-plus';
```
All components are named exports prefixed with `El`. Direct imports are tree-shakable. Using older `lib/` paths is deprecated.
Element Plus CSS
wrong:
```
import 'element-plus/lib/theme-chalk/index.css';
```
correct:
```
import 'element-plus/dist/index.css';
```
Essential for applying the default Element Plus theme and styling. The `dist/index.css` path is the current standard; older `lib/theme-chalk/` paths may be outdated.
ButtonInstance (type)
```
import type { ButtonInstance } from 'element-plus';
```
Useful for type-checking component refs (e.g., `const buttonRef = ref<ButtonInstance | null>(null);`) or other component-related types.

Quickstart

This quickstart demonstrates setting up a basic Vue 3 application with Element Plus, globally installing the library, importing its styles, and using several core components like ElButton, ElInput, and ElLink, along with programmatic usage of ElMessage.

import { createApp, ref } from 'vue';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import { ElMessage } from 'element-plus'; // For programmatic use

const App = {
  setup() {
    const inputValue = ref('');
    const message = ref('Hello Element Plus!');

    const showFeedback = () => {
      ElMessage.success('Button clicked!');
    };

    return {
      inputValue,
      message,
      showFeedback
    };
  },
  template: `
    <div style="text-align: center; margin-top: 50px;">
      <h1>{{ message }}</h1>
      <ElButton type="primary" @click="showFeedback">Click Me</ElButton>
      <ElInput 
        v-model="inputValue" 
        placeholder="Type something..."
        style="width: 300px; margin: 20px;"
      />
      <p v-if="inputValue">You typed: {{ inputValue }}</p>
      <ElLink href="https://element-plus.org/" target="_blank">Documentation</ElLink>
    </div>
  `
};

const app = createApp(App);
app.use(ElementPlus);
app.mount('#app');

view raw JSON →