Element UI Administrator & Developer Guide

1. Architecture Overview

Element UI is a comprehensive Vue 2.x component library providing 67+ UI components, a theme system built on SCSS, an i18n framework supporting 50+ languages, and a set of internal utilities for DOM manipulation, popup management, and form validation. The library is published as element-ui on npm (v2.15.14) and distributed as both ES module and UMD bundles.

Architecture Diagram

element-ui (npm package)
├── src/index.js                 ← Auto-generated entry, registers all 67+ components
│   ├── Vue.use(ElementUI)       ← Global install: components + directives + prototypes
│   └── Vue.prototype.$ELEMENT   ← Global config (size, zIndex)
│
├── packages/                    ← 67+ component packages
│   ├── {component}/index.js     ← Package entry (imports src/main.vue, sets install())
│   └── {component}/src/         ← Component implementation (.vue + .js)
│
├── src/
│   ├── mixins/                  ← Shared behaviors (emitter, focus, locale, migrating)
│   ├── directives/              ← Internal directives (mousewheel, repeat-click)
│   ├── locale/                  ← i18n engine + 50+ lang packs
│   ├── transitions/             ← Collapse transition component
│   └── utils/                   ← DOM, date, popup, popper, scrollbar, types, etc.
│
├── packages/theme-chalk/        ← SCSS theme (compiled via gulp to CSS)
│   └── src/                     ← Per-component .scss files + shared variables
│
├── types/                       ← TypeScript declarations
├── examples/                    ← Demo site (webpack-dev-server)
├── test/                        ← Unit tests (karma + mocha + chai + sinon)
└── build/                       ← Webpack configs + build scripts

Component Inventory

Element UI ships 67 registerable components plus the CollapseTransition utility component. They are organized into these categories:

Note

Components like Message, Notification, MessageBox, and Loading are dual-mode: they can be used as template components AND as imperative service calls via Vue.prototype methods (this.$message, this.$notify, this.$msgbox, this.$loading).

Technology Stack

Data Flow

Vue.use(ElementUI, options)
  │
  ├── locale.use(options.locale)          ← Set language
  ├── locale.i18n(options.i18n)           ← Set i18n handler
  ├── forEach component → Vue.component() ← Register all 67 components
  ├── Vue.use(InfiniteScroll)             ← Register directive
  ├── Vue.use(Loading.directive)          ← Register v-loading
  └── Vue.prototype.$ELEMENT = { size, zIndex }
      Vue.prototype.$loading = Loading.service
      Vue.prototype.$msgbox = MessageBox
      Vue.prototype.$alert = MessageBox.alert
      Vue.prototype.$confirm = MessageBox.confirm
      Vue.prototype.$prompt = MessageBox.prompt
      Vue.prototype.$notify = Notification
      Vue.prototype.$message = Message

2. System Requirements

Runtime Dependencies

Dev/Build Dependencies (selected)

Important

node-sass (used for building theme-chalk) is deprecated and may fail on Node 16+. If building themes locally, consider switching to sass (Dart Sass) or using the pre-built CSS from lib/theme-chalk/.

3. Configuration Reference

Global Configuration Object

When calling Vue.use(ElementUI, options), the options object is stored on Vue.prototype.$ELEMENT:

Locale Configuration

The i18n function receives (key, options) where key is a dot-separated path (e.g., el.table.confirmFilter) and options is an interpolation object.

Environment Variables

Tip

The migrating mixin (in src/mixins/migrating.js) logs console warnings for deprecated props and events. These only run when NODE_ENV !== 'production', so they help during development but have zero overhead in production.

Build Scripts

Build Outputs

4. Deployment & Scaling

Distribution

Element UI is consumed as an npm package. It does not run as a service or require server deployment. Distribution considerations:

Full import (~700KB unminified JS + ~230KB CSS):

import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
Vue.use(ElementUI);

Partial import (recommended for production):

Use babel-plugin-component to import only needed components and their styles. This can reduce the bundle to under 100KB for typical applications.

CDN deployment:

<link rel="stylesheet" href="https://unpkg.com/element-ui@2.15.14/lib/theme-chalk/index.css">
<script src="https://unpkg.com/element-ui@2.15.14/lib/index.js"></script>

SSR Considerations

Element UI supports server-side rendering with Vue SSR. Key points:

• All service components (Message, Notification, MessageBox, Loading service) include Vue.prototype.$isServer guards and no-op on the server
• The popup manager skips z-index management on the server
• DOM utilities (src/utils/dom.js) check for document existence before accessing it

Warning

The v-loading directive and InfiniteScroll directive access DOM APIs directly. When using Nuxt or other SSR frameworks, register Element UI as a client-only plugin.

Performance Optimization

5. Operations

Theme Customization System

Element UI's theme is built with SCSS and lives in packages/theme-chalk/:

packages/theme-chalk/
├── src/
│   ├── common/
│   │   └── var.scss          ← Master variable file (all design tokens)
│   ├── mixins/
│   │   ├── config.scss       ← BEM naming configuration
│   │   ├── function.scss     ← SCSS utility functions
│   │   └── mixins.scss       ← Shared component mixins
│   ├── fonts/                ← Icon font files
│   ├── index.scss            ← Main entry (imports all component styles)
│   ├── {component}.scss      ← Per-component stylesheet
│   └── date-picker/*.scss    ← Date picker sub-styles
├── gulpfile.js               ← Build: sass → autoprefixer → cssmin → lib/
└── package.json              ← Published as `element-theme-chalk`

Key theme variables (from src/common/var.scss):

Theme build pipeline:

# In packages/theme-chalk/
gulp build
# Steps: sass → autoprefixer → cssmin → lib/

Note

The theme uses BEM naming convention: el-{component}, el-{component}__{element}, el-{component}--{modifier}. The $namespace defaults to el.

Online Theme Editor

The demo site includes a theme configurator at examples/components/theme-configurator/. It allows:

• Live editing of SCSS variables
• Real-time preview of component styles
• Download of compiled custom theme
• Local storage persistence of user theme configs

Theme constants are stored via ELEMENT_THEME_USER_CONFIG and ELEMENT_THEME_PREVIEW_CONFIG localStorage keys.

i18n System

Architecture:

src/locale/
├── index.js        ← Locale engine: use(), i18n(), t()
├── format.js       ← String template interpolation
└── lang/           ← 50+ language packs (zh-CN, en, es, fr-FR, ja, ko, etc.)

How translation works:

1. Each component uses the locale mixin which provides this.t(key, options)
2. t() first tries the custom i18n handler (if registered via locale.i18n(fn))
3. Falls back to dot-path lookup in the active language pack
4. Interpolates {placeholders} via the format engine

Supported languages include: zh-CN (default), zh-TW, en, es, fr, de, ja, ko, pt, pt-br, ru, ar, it, nl, pl, sv, tr, vi, th, and 30+ more.

Tip

To add a new language, create a new file in src/locale/lang/ following the structure of any existing pack. The keys match the el.* namespace used throughout components.

Popup and Z-Index Management

The PopupManager (src/utils/popup/popup-manager.js) manages global z-index ordering for all overlay components:

• Base z-index starts from Vue.prototype.$ELEMENT.zIndex (default 2000)
• Each popup increments the global counter via PopupManager.nextZIndex()
• Modals register/deregister for body scroll locking
• The manager tracks a stack of open modals for correct ESC-key handling

6. Performance

Bundle Size

Partial imports can significantly reduce this. A typical app using 15-20 components may end up with ~150KB total (minified + gzipped).

Table Performance

The Table component (packages/table/src/) is the most complex component at 91KB of source across 12 files. Performance considerations:

• Fixed columns create shadow DOM copies of the table, doubling render cost
• Large datasets (1000+ rows) benefit from fixed height which enables virtual scrolling
• doLayout() should be called after visibility changes (tab switches, accordion opens) to recalculate column widths
• Memory leaks can occur if tables are shown/hidden with v-show instead of v-if — the layout observers may not clean up (issue #22980)

Note

The Table component uses a dedicated Vuex-like store (packages/table/src/store/) to manage column state, sorting, filtering, expansion, and selection. Each Table instance gets its own store.

Rendering Optimizations Built In

• Throttled scroll handlers in Table and InfiniteScroll via throttle-debounce
• ResizeObserver polyfill for responsive Table columns and Scrollbar
• Lazy rendering for TabPane (lazy prop) and Image (lazy prop)
• Virtual scrolling in Scrollbar component
• Transition caching via the CollapseTransition component
• Mouse event normalization via normalize-wheel for consistent scroll behavior

7. Security

XSS Prevention

Several components support dangerouslyUseHTMLString for rendering raw HTML:

Caution

When dangerouslyUseHTMLString is set to true, the content is rendered via v-html. Never pass unsanitized user input through these options. Always sanitize HTML before rendering to prevent cross-site scripting attacks.

Dependency Security

Content Security Policy

Element UI injects styles dynamically for:

• Loading overlay positioning
• Theme configurator live preview
• Popup z-index management

If your application enforces strict CSP (style-src without 'unsafe-inline'), the Loading directive's inline style injection will fail. Use the service API with pre-defined classes instead.

8. Developer Internals

Repository Structure

.
├── build/                          ← Build scripts and webpack configs
│   ├── bin/
│   │   ├── build-entry.js          ← Auto-generates src/index.js from components.json
│   │   ├── iconInit.js             ← Generates icon list from theme-chalk
│   │   ├── i18n.js                 ← Generates i18n page data
│   │   ├── version.js              ← Writes version file
│   │   ├── gen-cssfile.js          ← Generates per-component CSS imports
│   │   └── build-locale.js         ← Builds UMD locale bundles
│   ├── webpack.conf.js             ← UMD full bundle config
│   ├── webpack.common.js           ← CommonJS full bundle config
│   ├── webpack.component.js        ← Per-component CommonJS bundles
│   └── webpack.demo.js             ← Demo site dev server config
├── examples/                       ← Demo website (Vue SPA)
│   ├── app.vue                     ← Root component
│   ├── entry.js                    ← Webpack entry
│   ├── route.config.js             ← Router (loads doc pages from examples/docs/)
│   ├── nav.config.json             ← Navigation structure
│   ├── docs/                       ← Markdown documentation (zh-CN, en-US, es, fr-FR)
│   ├── components/                 ← Theme editor, search, demo components
│   └── i18n/                       ← Demo site i18n (page titles, labels)
├── packages/                       ← Component packages (67+)
│   ├── {component}/
│   │   ├── index.js                ← Package entry: imports + sets install()
│   │   └── src/
│   │       ├── main.vue            ← Component implementation (SFC)
│   │       └── *.js                ← Supporting logic
│   └── theme-chalk/                ← SCSS theme package
├── src/                            ← Shared infrastructure
│   ├── index.js                    ← Master entry (auto-generated)
│   ├── mixins/                     ← Shared component behaviors
│   ├── directives/                 ← Internal directives
│   ├── locale/                     ← i18n engine + language packs
│   ├── transitions/                ← Animation components
│   └── utils/                      ← Utility library (17 files, ~100KB)
├── test/                           ← Test suites
│   ├── unit/                       ← Karma + Mocha unit tests
│   │   ├── karma.conf.js           ← Karma configuration
│   │   ├── index.js                ← Test entry (requires all spec files)
│   │   ├── specs/                  ← Per-component test specs
│   │   └── mocks/                  ← Test mocks
│   └── ssr/                        ← Server-side rendering tests
├── types/                          ← TypeScript declarations
│   ├── index.d.ts                  ← Master type entry
│   ├── element-ui.d.ts             ← Main module types
│   └── {component}.d.ts            ← Per-component types
├── components.json                 ← Component registry (name → path mapping)
├── web-types.json                  ← JetBrains IDE component metadata
├── package.json                    ← Package manifest
├── Makefile                        ← Build shortcuts
└── .travis.yml                     ← CI configuration (Node 10, Chrome)

Component Architecture Pattern

Every component follows the same pattern:

1. Package entry (packages/{name}/index.js):

import Component from './src/main';

Component.install = function(Vue) {
  Vue.component(Component.name, Component);
};

export default Component;

2. Component SFC (packages/{name}/src/main.vue):

• Uses componentName (internal) for the emitter mixin's dispatch/broadcast
• Injects parent context where needed (e.g., inject: ['elForm'])
• Provides context to children (e.g., provide() { return { elFormItem: this } })
• Uses the locale mixin for this.t() translations
• Uses the emitter mixin for cross-component communication
• Uses the migrating mixin for deprecation warnings

3. Service components (Message, Notification, Loading, MessageBox) follow a constructor pattern:

const Constructor = Vue.extend(MainComponent);
const instance = new Constructor({ data: options });
instance.$mount();
document.body.appendChild(instance.$el);

Mixin System

The emitter mixin is critical infrastructure — it replaces Vue's removed $dispatch and $broadcast by walking the component tree via $parent / $children and matching on componentName.

Utility Library

The src/utils/ directory (17 files, ~100KB) provides:

Error Messages Reference

The following error messages are thrown from source code:

Directives

Public directives (registered via Vue.use):

Internal directives (not publicly registered):

Testing Strategy

Framework: Karma + Mocha + Chai + Sinon

Configuration: test/unit/karma.conf.js configures Chrome headless, webpack preprocessing, Istanbul coverage, and spec reporter.

Test entry: test/unit/index.js requires all *.spec.js files from test/unit/specs/.

Coverage: Istanbul instrumentation via babel-plugin-istanbul, output to test/unit/coverage/.

SSR tests: test/ssr/require.test.js verifies that all components can be required in a Node.js environment without DOM errors.

Running tests:

# Full test suite (lint + build theme + karma)
npm test

# Watch mode (auto-rerun on changes)
npm run test:watch

Note

Tests require Chrome (via karma-chrome-launcher). The .travis.yml configures addons: chrome: stable for CI.

Code Patterns and Conventions

BEM naming: All CSS classes follow el-{block}__{element}--{modifier} pattern.

Component naming: PascalCase in JS (ElButton), kebab-case in templates (<el-button>). Internal componentName property used by the emitter mixin.

JSX render functions: Table, Select, Autocomplete, and several other complex components use JSX render functions (via babel-plugin-transform-vue-jsx) instead of templates for dynamic rendering.

Component communication:

• Parent → Child: props
• Child → Parent: $emit events
• Cross-level: emitter mixin's dispatch (bubbles up to named ancestor) and broadcast (propagates down to named descendant)
• Dependency injection: provide/inject for Form → FormItem, Select → Option, etc.

Auto-generated files:

• src/index.js — generated by build/bin/build-entry.js from components.json
• Icon list — generated by build/bin/iconInit.js from theme-chalk icon font
• i18n pages — generated by build/bin/i18n.js

Potential Improvements

Based on the current codebase and community issues:

1. Upgrade lodash to 4.17.21+ — current devDependency has known prototype pollution vulnerabilities (issues #23127, #23132)
2. Migrate from node-sass to Dart Sass — node-sass is deprecated and causes build failures on modern Node versions
3. Table memory leak mitigation — ResizeObserver and event listeners in Table may not properly clean up (issue #22980)
4. Fixed column + summary scrollbar fix — Known interaction bug between fixed columns and summary row (issues #23142, #20515)
5. Upgrade async-validator — Pinned to ~1.8.1; newer versions include important fixes but may change validation behavior
6. Babel 6 → 7 migration — Build toolchain uses Babel 6 which is EOL
7. Webpack 4 → 5 migration — Webpack 4 is in maintenance mode

9. Integration Points

Vue Router Integration

The <el-menu> component supports router mode — setting router prop causes menu items to navigate using their index as the route path:

<el-menu router :default-active="$route.path">
  <el-menu-item index="/dashboard">Dashboard</el-menu-item>
  <el-menu-item index="/settings">Settings</el-menu-item>
</el-menu>

<el-breadcrumb-item> supports the :to prop for Vue Router navigation.

vue-i18n Integration

Element UI integrates with vue-i18n through the i18n install option. The handler receives the translation key and interpolation options, allowing Element UI's internal translations to merge with your application's translations.

Form Validation (async-validator)

Element UI's Form component uses async-validator v1.8.x for validation rules. Rules support:

TypeScript Support

Type declarations ship in the types/ directory:

import Vue from 'vue';
import ElementUI from 'element-ui';

Vue.use(ElementUI);

// Component types
import { ElButton } from 'element-ui/types/button';

// Service types
import { ElMessageBox } from 'element-ui/types/message-box';

The types/index.d.ts augments Vue with the $ELEMENT, $message, $notify, $msgbox, $alert, $confirm, $prompt, and $loading prototype methods.

JetBrains IDE Support

The web-types.json file at the package root provides component metadata (props, events, slots, descriptions) for JetBrains IDEs (WebStorm, IntelliJ). This enables auto-completion and inline documentation for all Element UI components.

Tip

VS Code users can get similar auto-completion through the Vetur extension, which reads component type definitions and the web-types.json file.