Element UI to Element Plus: A Practical Migration Map for Enterprise Dashboards

Before touching Vue core, we tag screens by the Element controls they use. In practice, the time sinks are: el-table with custom column slots, nested dialogs + drawer stacks, el-form with async rules, and global $message / $notify usage (imperative APIs you will trace through every file).

If you ship in multiple languages, your Element Plus locale config must be paired with app-level i18n so strings and date formats stay aligned. A partial migration (English Plus + legacy Vue 2 in another locale) is a support trap—treat i18n as a release gate, not a follow-up.

We prefer vertical slices: migrate a domain (billing, org admin, reporting) to Vue 3 with Element Plus end-to-end, with feature flags behind routes. If you federate or run multiple deployables, align package versions per shell so you do not ship two major Element lineages at once.

• Print / PDF flows where el-table width math changed
• Keyboard and focus order through nested overlays
• Row virtualization or infinite scroll, if you brought third-party add-ons in Vue 2

el-table is where most enterprise Element migrations stall. The breaking changes look small in the docs and large in production, especially around scoped slots and column rendering.

Before (Vue 2 / Element UI)

<el-table :data="rows">
  <el-table-column label="Status">
    <template slot-scope="scope">
      <status-badge :value="scope.row.status" />
    </template>
  </el-table-column>
</el-table>

After (Vue 3 / Element Plus)

<el-table :data="rows">
  <el-table-column label="Status">
    <template #default="scope">
      <status-badge :value="scope.row.status" />
    </template>
  </el-table-column>
</el-table>

The mechanical change is trivial. The traps are:

• Render functions in column definitions using render-header or scopedSlots generators must be rewritten. They were usually copy-pasted from a senior dev's gist three years ago and nobody knows why.
• Custom sort and filter functions receive arguments in slightly different shapes. Snapshot tests catch this; visual review does not.
• Fixed columns (fixed="left") now use CSS position: sticky. Older browsers and print styles need verification.
• Virtualized tables in Element Plus use el-table-v2 with a different API; this is a port, not an upgrade.

Element UI patched the Vue prototype: this.$message, this.$notify, this.$confirm, this.$msgbox. Element Plus exports them as named imports. That is correct, but it means every call site changes.

// before
this.$message.success("Saved");

// after
import { ElMessage } from "element-plus";
ElMessage.success("Saved");

Two pragmatic options:

• Codemod everything. A jscodeshift script handles the simple cases; the awkward cases (e.g. this.$confirm(...).then(...)) need a hand-pass.
• Wrap with a thin facade. Re-export the imperative APIs from @/lib/notify.ts, then import from there everywhere. Future moves (away from Element entirely, for example) become a one-file change.

Element UI used SCSS variables compiled into a single theme. Element Plus uses CSS custom properties, which makes runtime theming and dark mode straightforward — but every legacy SCSS override file must be revisited.

• Replace $--color-primary overrides with --el-color-primary CSS variables.
• Move dark-mode toggles to the html.dark selector recommended by Element Plus.
• If you use a corporate design token package, audit which tokens map to which Element Plus variables. This is the cleanest moment to consolidate; coordinate with any design system extraction work in progress.

• Print stylesheets break silently. CSS variable cascading interacts with @media print in ways that flat SCSS variables did not. QA your PDF and "print to PDF" flows.
• Form validation timing. Async rules resolved synchronously in some Element UI corners. Element Plus is strict about Promises. Race conditions with debounced server-side checks surface immediately.
• Locale defaults. Element UI fell back to English when no locale was registered. Element Plus warns and ships untranslated keys. Pair locale registration with vue-i18n bootstrap.
• el-popover teleport target. Default changed; popovers may render inside scrolled containers in unexpected places. Set teleported="false" selectively.
• Auto-import + global styles double up. If you mix unplugin-vue-components auto-import with a global Element Plus import, CSS bundles inflate. Pick one strategy.

1. Inventory. Grep every el-* tag and $message / $notify / $confirm call. Tag screens by complexity (table-heavy, form-heavy, simple).
2. Wrap imperative APIs. Introduce @/lib/notify.ts in the Vue 2 codebase first, so the cutover is mechanical.
3. Pick a vertical slice. One domain, one route group, one feature flag. We typically start with an internal admin screen — production traffic, low blast radius.
4. Run codemods on the slice. slot-scope → #default, .sync → v-model, prototype methods → named imports.
5. Hand-pass el-table columns. This is the one place codemods reliably miss edge cases.
6. QA pass. Print/PDF, keyboard order, IME input, locale parity. Add Cypress component tests where coverage is thin — see our Cypress component testing post.
7. Soak in production behind a flag for one release cycle. Compare error rates against the Vue 2 baseline.
8. Move to the next slice. Track velocity per slice; estimates compound, and the second slice should be ~30% faster than the first.

• "Migrate Element first, then Vue." Element Plus does not run on Vue 2. Element UI does not run on Vue 3. They are coupled migrations.
• Forking Element UI to add Vue 3 support. Some teams attempt this. The maintenance cost dwarfs the migration cost within 6 months.
• Big-bang switch over a weekend. Enterprise dashboards have long-tail behaviors (saved filters, exported PDFs, scheduled jobs that hit the same UI). Slice migrations win.
• Skipping the wrapper layer for imperative APIs. Direct ElMessage imports everywhere couples your code tighter to Element Plus than necessary.
• Treating @vue/compat as the bridge. Compat does not help with Element — both libraries must move together. Coordinate this with the broader strangler fig pattern.

Conclusion

Element Plus is the right successor for most Element UI codebases, but the migration effort tracks how deeply your product relied on table and form composition—not how many el-button tags you have. Sequence the painful surfaces early and you will de-risk the rest of the Vue 3 work.