# Element Plus: a Vue 3 component library for teams migrating from Element UI

> Element Plus is the Vue 3 rewrite of the Element UI component set, written in TypeScript and licensed MIT. Its real draw is the migration path from Element UI, and its real cost is a full framework and build-tool move.

**element-plus/element-plus** — A Vue.js 3 UI Library made by Element team. 中国大陆加速镜像站点 Breaking Change List The first stable release of Element Plus, suitable for production use, was released on February 7, 2022.

- Repository: https://github.com/element-plus/element-plus
- Website: https://element-plus.org
- Stars: 27,794 · Forks: 19,821
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/element-plus-element-plus

## What Element Plus solves, and who it is actually for

Element Plus is a Vue.js 3 UI library from the Element team, written in TypeScript. It targets application developers building admin panels, dashboards and internal tools, the kind of interface where a data table, a form, a date picker and a dialog cover most of the screen. The README frames the project around two things: the Vue 3 Composition API and TypeScript. Those are also the two reasons the library exists as a separate package rather than as a version bump of Element UI.

Element UI was built for Vue 2. When Vue 3 arrived with a new reactivity system and the Composition API, the old component internals could not simply be ported in place. Element Plus is that port, and the repository keeps a dedicated breakings/ directory alongside a published Breaking Change List discussion, which tells you the maintainers treat the upgrade path as a first-class artifact rather than a footnote. The first stable release, described in the README as suitable for production use, was published on February 7, 2022, so the API has had several years of settling.

The audience is narrow in a useful way. If you are starting a Vue 3 project and you want a full component set with a Chinese-language documentation mirror (the README links a mainland acceleration site), Element Plus is aimed at you. If you are picking a design system for a marketing site with bespoke visuals, it is not.

## How the library is put together: monorepo, theme package and playground

The repository is a pnpm workspace. The top-level package.json declares packageManager pnpm@12.4.1 and lists workspaces as packages/*, play and docs. Component source lives under packages/, the documentation site is a VitePress project under docs/, and play/ is a local development app used to exercise components during development. A separate packages/theme-chalk package holds the stylesheet layer, and the root scripts expose build:theme for it, which means the CSS is built as its own artifact rather than being bundled into every component import.

That split matters when you debug styling. A component's behavior and its appearance ship from different build steps, so a class that looks unstyled usually points at the theme layer rather than at the component. The root scripts also show the intended development flow: pnpm dev runs the play app, and pnpm test runs Vitest, with a separate pnpm test:ssr target that uses the ssr-testing/vitest.config.ts configuration. Server-side rendering is tested as its own concern, not as an afterthought.

Type checking is not a single command. The package.json defines typecheck:web, typecheck:play, typecheck:node, typecheck:vite-config and typecheck:vitest, each pointing at a different tsconfig file, and typecheck runs all of them through a glob. That is a fair signal of how much the project leans on TypeScript, and it is also a warning for contributors: a change can pass one typecheck target and fail another.

## Installing Element Plus and rendering a first component

The README points developers who intend to build websites to the Getting Started page at element-plus.org rather than repeating install steps, so the package name is the part you can rely on from the repository itself: element-plus, published on npm. The related searches include "element-plus npm", which is the right instinct. The repository's own package.json is the private workspace root and does not declare element-plus as a dependency, so install the published package with your package manager of choice.

```bash
pnpm add element-plus
```

The README does not spell out the import syntax, so check the Getting Started page for the current form before copying anything from a blog post. What the repository does confirm is that the styles come from a separate theme package, packages/theme-chalk, so a working setup needs that stylesheet registered alongside the components.

If you would rather not commit to the whole library before evaluating it, the README offers two zero-install routes: the built-in playground at element-plus.run, and a CodeSandbox template linked from the same section. Both are the fastest way to check whether a table or a select behaves the way your design expects.

For component-level experimentation, the repository root scripts define dev as running the play workspace app.

```bash
pnpm dev
```

## Migrating an Element UI project, and where that migration goes wrong

The migration story is the most concrete thing in the README. There is a Breaking Change List discussion linked from the repository, and a gogocode migration tool in the thx/gogocode repository under packages/gogocode-plugin-element. The README states the tool was tested on Vue Element Admin and links the transpiled result, which is a more useful claim than a generic "it works" because you can read the output diff yourself.

An automated codemod of this kind rewrites component tags, prop names and event names. It does not rewrite your application logic. Anything you built around the old component internals, such as a wrapper that reached into a component instance, a slot name that changed, or a style override keyed to an internal class, survives the codemod untouched and breaks at runtime instead. Treat the tool as the first pass, not the migration. The breakings/ directory in the repository exists precisely because the list of changes is long enough to need versioning.

The harder constraint is the one nobody can codemod away: Vue 2 to Vue 3. Element Plus requires Vue 3, so adopting it means your build tooling, your router, your state library and your test setup all move too. Teams that frame this as "upgrade the UI library" underestimate it. The UI library is the visible part; the framework swap is the actual project.

## Where Element Plus is the wrong choice

The clearest boundary is Vue 2. If your application is on Vue 2 and you are not migrating the framework, Element Plus is not an option, and Element UI remains the line for that. The related searches show people conflating the two names, which is understandable given the shared heritage, but they are different packages for different Vue majors.

A second boundary is scope. Element Plus is a complete component set with opinions about markup, class names and default styling. If your team wants to own the visual layer and only needs behavior, a headless approach plus a utility CSS framework will fight you less than overriding a themed component library will. The search data shows people comparing Element Plus against Tailwind, which is a category mismatch: one ships rendered components, the other ships utility classes. Comparisons against PrimeVue, Vuetify, Naive UI, Quasar and Ant Design are closer to like-for-like, and the deciding factor in each case is usually which framework ecosystem you are already committed to, not which component set is objectively better.

A third boundary is documentation language. The project provides English and Chinese versions, and the README states that more translations are pending on Crowdin due to limited resources. If your team needs first-class docs in another language, budget for that gap.

## A real alternative and the difference in approach

Vuetify is the most direct alternative for a Vue 3 team, and the difference is philosophical rather than cosmetic. Element Plus ships a component set with a theme package (packages/theme-chalk) that you override through CSS variables and class selectors. Vuetify builds on Material Design and exposes a configuration object and a grid system as the primary customization surface, so spacing, breakpoints and color are driven from configuration rather than from stylesheet overrides.

In practice: if your designers hand you a spec that resembles Material, Vuetify's defaults get you closer with less work. If your designers hand you a spec that resembles Element, Element Plus does. The migration tooling is also asymmetric. Element Plus has a documented codemod for Element UI projects and a published breaking-change list; a team coming from Vuetify 2 to Vuetify 3 gets a migration guide, not a transpiler. That specific artifact is why a Vue 2 shop with an existing Element UI codebase has a stronger reason to pick Element Plus than a greenfield team does.

## Maintenance, release cadence and what MIT means here

The repository is not archived. The last push was on 2026-08-21, which is under a month before today, and the release history shows 2.14.5 on 2026-08-21, 2.14.4 on 2026-08-07 and 2.14.3 on 2026-07-10. That is a steady patch cadence on the 2.14 line, with a new patch roughly every two to four weeks. For a component library, patch releases at that rhythm usually mean bug fixes and documentation updates rather than new surface area, though the CHANGELOG.en-US.md file in the repository root is where you confirm that for any given version.

Element Plus is MIT licensed. In practical terms, that permits commercial use, modification and redistribution with the licence text retained, and it does not impose copyleft obligations on your application. It also means no warranty is provided. This is a description of the licence text, not legal advice; if your organization has a policy review for third-party dependencies, the LICENSE file in the repository root is the document to hand over.

Upgrade cost is where the versioning discipline shows. The project maintains a breaking-change list and a breakings/ directory, which implies that minor releases can carry breaking changes. Pin your version, read the changelog before bumping, and keep the migration tool in mind as a reference for what tends to change between majors.

## Conclusion

Adopt Element Plus if you are on Vue 3 and want the Element UI component vocabulary with Composition API support and TypeScript types; the last push was on 2026-08-21 and the latest release is 2.14.5. Do not adopt it if you are staying on Vue 2, since Element UI remains the Vue 2 line, or if you need a headless styling-first approach, where Tailwind or a headless library fits better. Before committing, check the Breaking Change List discussion for the components you use, and run the gogocode migration tool on a branch to see what it rewrites.

## FAQ

### Is Element Plus free?

Yes. The README states that Element Plus is open source software licensed as MIT, which permits commercial use and modification as long as the licence terms are met.

### How do I install Element Plus?

It is published on npm as element-plus, so you install it with your package manager, for example pnpm add element-plus. The README directs developers building websites to the Getting Started page at element-plus.org for the full setup, and the styles come from a separate theme package.

### What is Element UI?

Element UI is the earlier Vue 2 component library from the same team. The README provides a breaking change list and a gogocode migration tool for moving a project from Element UI to Element Plus, and links a transpiled Vue Element Admin as an example result.

### Which is better, PrimeVue or Element Plus?

The README does not rank the two. The practical difference it supports is ecosystem: Element Plus is a Vue 3 library written in TypeScript with a documented migration path from Element UI, so it fits teams already in that lineage, while PrimeVue is a separate component set with its own API and theming.

### What is Element Plus?

It is a Vue.js 3 UI library made by the Element team and written in TypeScript. The README describes it as using the Vue 3 Composition API, and states that the first stable release suitable for production use was published on February 7, 2022.

## Sources

- [Official documentation](https://element-plus.org)
- [Official README](https://github.com/element-plus/element-plus#readme)
- [Project repository](https://github.com/element-plus/element-plus)
- [Release notes](https://github.com/element-plus/element-plus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/element-plus-element-plus