Element Plus Vue3

When to use this skill

Use this skill whenever the user wants to:

• Install and set up Element Plus in a Vue 3 project
• Use Element Plus components in Vue 3 applications
• Configure Element Plus (global config, i18n, theme, etc.)
• Use form components (Button, Input, Form, etc.)
• Use data display components (Table, Card, etc.)
• Use feedback components (Message, Notification, Dialog, etc.)
• Use navigation components (Menu, Tabs, etc.)
• Customize component styles and themes
• Handle component events
• Understand Element Plus API and methods
• Troubleshoot Element Plus issues

How to use this skill

This skill is organized to match the Element Plus official documentation structure (https://element-plus.org/zh-CN/, https://element-plus.org/en-US/guide/design, https://element-plus.org/en-US/component/overview). When working with Element Plus:

1. Identify the topic from the user's request:

• Installation/安装 → examples/guide/installation.md
• Quick Start/快速开始 → examples/guide/quick-start.md
• Design/设计 → examples/guide/design.md
• Components/组件 → examples/components/
• API/API 文档 → api/

2. Load the appropriate example file from the examples/ directory:

Guide (使用指南):

• examples/guide/installation.md - Installation guide
• examples/guide/quick-start.md - Quick start guide
• examples/guide/design.md - Design guidelines
• examples/guide/i18n.md - Internationalization
• examples/guide/theme.md - Theme customization
• examples/guide/global-config.md - Global configuration

Components (组件):

• examples/components/overview.md - Components overview
• examples/components/button.md - Button component
• examples/components/input.md - Input component
• examples/components/form.md - Form component
• examples/components/table.md - Table component
• examples/components/card.md - Card component
• examples/components/dialog.md - Dialog component
• examples/components/message.md - Message component
• examples/components/notification.md - Notification component
• examples/components/menu.md - Menu component
• examples/components/tabs.md - Tabs component
• examples/components/date-picker.md - DatePicker component
• examples/components/select.md - Select component
• examples/components/switch.md - Switch component
• examples/components/checkbox.md - Checkbox component
• examples/components/radio.md - Radio component
• examples/components/upload.md - Upload component
• examples/components/pagination.md - Pagination component
• examples/components/tree.md - Tree component
• examples/components/tree-select.md - TreeSelect component
• examples/components/transfer.md - Transfer component
• examples/components/descriptions.md - Descriptions component
• examples/components/avatar.md - Avatar component
• examples/components/badge.md - Badge component
• examples/components/tag.md - Tag component
• examples/components/empty.md - Empty component
• examples/components/loading.md - Loading component
• examples/components/popover.md - Popover component
• examples/components/tooltip.md - Tooltip component
• examples/components/dropdown.md - Dropdown component
• examples/components/drawer.md - Drawer component
• examples/components/popconfirm.md - Popconfirm component

3. Follow the specific instructions in that example file for syntax, structure, and best practices

Important Notes:

• Element Plus is for Vue 3 only
• Components use Vue 3 Composition API
• Examples include both Options API and Composition API
• Each example file includes key concepts, code examples, and key points

4. Reference API documentation in the api/ directory when needed:

• api/component-api.md - Component API reference
• api/props-and-events.md - Props and events reference
• api/global-config.md - Global configuration API

5. Use templates from the templates/ directory:

• templates/installation.md - Installation templates
• templates/component-usage.md - Component usage templates
• templates/project-setup.md - Project setup templates

1. Understanding Element Plus

Element Plus is a Vue 3 component library that provides a rich set of UI components following Element Design principles.

Key Concepts:

• Vue 3 Support: Built for Vue 3 with Composition API
• Design System: Follows Element Design language
• Rich Components: 60+ components for various use cases
• Theme Customization: Support for theme customization
• i18n: Internationalization support
• TypeScript: Full TypeScript support

2. Installation

Using npm:

npm install element-plus

Using yarn:

yarn add element-plus

Using pnpm:

pnpm add element-plus

3. Basic Setup

Full Import:

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

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

On-Demand Import:

import { ElButton, ElInput } from 'element-plus'
import 'element-plus/es/components/button/style/css'
import 'element-plus/es/components/input/style/css'

Doc mapping (one-to-one with official documentation)

Guide (指南):

• See guide files in examples/guide/ or examples/getting-started/ → https://element-plus.org/en-US/guide/design

Components (组件):

• See component files in examples/components/ → https://element-plus.org/en-US/component/overview

Examples and Templates

This skill includes detailed examples organized to match the official documentation structure. All examples are in the examples/ directory (see mapping above).

To use examples:

• Identify the topic from the user's request
• Load the appropriate example file from the mapping above
• Follow the instructions, syntax, and best practices in that file
• Adapt the code examples to your specific use case

To use templates:

• Reference templates in templates/ directory for common scaffolding
• Adapt templates to your specific needs and coding style

API Reference

Detailed API documentation is available in the api/ directory, organized to match the official Element Plus API documentation structure:

Component API (api/component-api.md)

• Component props and events
• Component methods
• Component slots

Props and Events (api/props-and-events.md)

• Common props
• Common events
• Event handling

Global Configuration (api/global-config.md)

• Global configuration options
• ConfigProvider usage
• Theme configuration

To use API reference: 1. Identify the API you need help with 2. Load the corresponding API file from the api/ directory 3. Find the API signature, parameters, return type, and examples 4. Reference the linked example files for detailed usage patterns 5. All API files include links to relevant example files in the examples/ directory

Best Practices

1. Use on-demand import: Import only the components you need to reduce bundle size 2. Use Composition API: Prefer Composition API for better code organization 3. Handle events properly: Use proper event handlers for component interactions 4. Customize theme: Use theme variables for customization 5. Follow design specs: Follow Element Design specifications 6. Use TypeScript: Leverage TypeScript for better type safety

Resources

• Official Documentation: https://element-plus.org/zh-CN/
• English Documentation: https://element-plus.org/en-US/
• Design Guide: https://element-plus.org/en-US/guide/design
• Component Overview: https://element-plus.org/en-US/component/overview
• GitHub Repository: https://github.com/element-plus/element-plus

Keywords

Element Plus, element-plus, Vue 3, Vue3, UI components, component library, 组件库, 按钮, 表单, 表格, 弹窗, 消息, 通知, 菜单, 标签页, 日期选择器, 选择器, 开关, 复选框, 单选框, 上传, 分页, 树形控件, 穿梭框, 描述列表, 头像, 徽标, 标签, 空状态, 加载, 弹出框, 提示, 下拉菜单, 抽屉, 气泡确认框, Button, Form, Table, Dialog, Message, Notification, Menu, Tabs, DatePicker, Select, Switch, Checkbox, Radio, Upload, Pagination, Tree, Transfer, Descriptions, Avatar, Badge, Tag, Empty, Loading, Popover, Tooltip, Dropdown, Drawer, Popconfirm

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异 2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查 3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码 4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本 5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。

Component API

API Reference

Element Plus component props, events, and methods.

Common Props

Most components support:

• size - Component size (large, default, small)
• disabled - Disabled state
• className - Custom class name
• style - Custom style

Common Events

Most components emit:

• @click - Click event
• @change - Change event
• @focus - Focus event
• @blur - Blur event

Button Component

Props:

• type - Button type (primary, success, info, warning, danger)
• size - Button size (large, default, small)
• disabled - Disabled state
• loading - Loading state
• plain - Plain button
• round - Round button
• circle - Circle button
• icon - Icon component

Events:

• @click - Click event

Input Component

Props:

• v-model - Input value
• type - Input type (text, password, textarea)
• size - Input size (large, default, small)
• disabled - Disabled state
• readonly - Readonly state
• clearable - Show clear button
• show-password - Show password toggle
• placeholder - Placeholder text
• maxlength - Max length

Events:

• @input - Input event
• @change - Change event
• @focus - Focus event
• @blur - Blur event

Slots:

• prefix - Prefix content
• suffix - Suffix content
• prepend - Prepend content
• append - Append content

Form Component

Props:

• model - Form data object
• rules - Validation rules
• label-width - Label width
• label-position - Label position (left, right, top)

Methods:

• validate - Validate form
• validateField - Validate specific field
• resetFields - Reset form fields
• clearValidate - Clear validation

Events:

• @validate - Validation event

Table Component

Props:

• data - Table data
• columns - Table columns
• stripe - Stripe rows
• border - Show border
• size - Table size

Events:

• @selection-change - Selection change event
• @row-click - Row click event
• @sort-change - Sort change event

See also: examples/components/ for detailed component examples

Global Configuration

API Reference

Element Plus global configuration options.

Global Config Options

When using app.use(ElementPlus, options), you can pass:

interface ElementPlusOptions {
  size?: 'large' | 'default' | 'small'
  zIndex?: number
  locale?: Locale
}

ConfigProvider Props

Props:

• size - Global size (large, default, small)
• zIndex - Global z-index (default: 3000)
• locale - Locale object
• button - Button config
• message - Message config

Example: Global Config

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

const app = createApp(App)
app.use(ElementPlus, {
  size: 'large',
  zIndex: 3000,
  locale: zhCn
})

Example: ConfigProvider

<template>
  <el-config-provider
    :size="size"
    :z-index="zIndex"
    :locale="locale"
  >
    <el-button>Button</el-button>
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

const size = ref('default')
const zIndex = ref(3000)
const locale = ref(zhCn)
</script>

Size Configuration

Options:

• 'large' - Large size
• 'default' - Default size
• 'small' - Small size

z-index Configuration

Default: 3000

Controls z-index for overlays (Dialog, Drawer, etc.).

Locale Configuration

Import locale from element-plus/dist/locale/:

• zh-cn.mjs - Chinese (Simplified)
• en.mjs - English
• es.mjs - Spanish
• fr.mjs - French
• ja.mjs - Japanese
• ko.mjs - Korean

See also: examples/guide/i18n.md for i18n examples

Props and Events

API Reference

Common props and events in Element Plus components.

Common Props

size

Type: 'large' | 'default' | 'small'

Component size.

disabled

Type: boolean

Default: false

Whether component is disabled.

className

Type: string

Custom CSS class name.

style

Type: string | object

Custom inline style.

Common Events

@click

Type: Function

Click event handler.

Example:

<el-button @click="handleClick">Button</el-button>

@change

Type: Function

Change event handler.

Example:

<el-input v-model="value" @change="handleChange" />

@focus

Type: Function

Focus event handler.

Example:

<el-input @focus="handleFocus" />

@blur

Type: Function

Blur event handler.

Example:

<el-input @blur="handleBlur" />

Event Object

Event handlers receive an event object:

handleEvent(event) {
  // event.target - Target element
  // event.currentTarget - Current target element
  // event.detail - Event detail (component-specific)
}

Component-Specific Events

Different components emit different events:

• Input: @input, @change, @focus, @blur
• Select: @change, @visible-change
• Table: @selection-change, @row-click, @sort-change
• Form: @validate

See also: examples/components/ for component-specific examples

Button Component

官方文档: https://element-plus.org/en-US/component/button.html

Instructions

This example demonstrates the Button component in Element Plus.

Key Concepts

• Button types
• Button sizes
• Button states
• Button groups
• Button events

Example: Basic Button

<template>
  <el-button>Default</el-button>
  <el-button type="primary">Primary</el-button>
  <el-button type="success">Success</el-button>
  <el-button type="info">Info</el-button>
  <el-button type="warning">Warning</el-button>
  <el-button type="danger">Danger</el-button>
</template>

Example: Button Sizes

<template>
  <el-button size="large">Large</el-button>
  <el-button size="default">Default</el-button>
  <el-button size="small">Small</el-button>
</template>

Example: Button States

<template>
  <el-button disabled>Disabled</el-button>
  <el-button loading>Loading</el-button>
  <el-button plain>Plain</el-button>
  <el-button round>Round</el-button>
  <el-button circle>Circle</el-button>
</template>

Example: Button Events

<template>
  <el-button type="primary" @click="handleClick">
    Click Me
  </el-button>
</template>

<script setup>
const handleClick = () => {
  console.log('Button clicked')
}
</script>

Example: Button Group

<template>
  <el-button-group>
    <el-button type="primary" icon="ArrowLeft">Previous</el-button>
    <el-button type="primary" icon="ArrowRight">Next</el-button>
  </el-button-group>
</template>

Example: Button with Icon

<template>
  <el-button type="primary" icon="Search">Search</el-button>
  <el-button type="primary" :icon="Search">Search</el-button>
</template>

<script setup>
import { Search } from '@element-plus/icons-vue'
</script>

Key Points

• Multiple types: primary, success, info, warning, danger
• Multiple sizes: large, default, small
• Support disabled, loading, plain, round, circle
• Icon support
• Button group support

DatePicker Component

官方文档: https://element-plus.org/en-US/component/date-picker.html

Instructions

This example demonstrates the DatePicker component in Element Plus.

Key Concepts

• Date selection
• Date range
• Date format
• Date picker types

Example: Basic DatePicker

<template>
  <el-date-picker v-model="date" type="date" placeholder="Select date" />
</template>

<script setup>
import { ref } from 'vue'

const date = ref('')
</script>

Example: Date Range

<template>
  <el-date-picker
    v-model="dateRange"
    type="daterange"
    range-separator="To"
    start-placeholder="Start date"
    end-placeholder="End date"
  />
</template>

<script setup>
import { ref } from 'vue'

const dateRange = ref([])
</script>

Example: Date Picker Types

<template>
  <el-date-picker v-model="date" type="date" />
  <el-date-picker v-model="datetime" type="datetime" />
  <el-date-picker v-model="daterange" type="daterange" />
  <el-date-picker v-model="datetimerange" type="datetimerange" />
  <el-date-picker v-model="month" type="month" />
  <el-date-picker v-model="year" type="year" />
</template>

Example: Date Format

<template>
  <el-date-picker
    v-model="date"
    type="date"
    format="YYYY-MM-DD"
    value-format="YYYY-MM-DD"
  />
</template>

Example: Date Picker with Shortcuts

<template>
  <el-date-picker
    v-model="date"
    type="date"
    :shortcuts="shortcuts"
  />
</template>

<script setup>
import { ref } from 'vue'

const date = ref('')
const shortcuts = [
  {
    text: 'Today',
    value: new Date()
  },
  {
    text: 'Yesterday',
    value: () => {
      const date = new Date()
      date.setTime(date.getTime() - 3600 * 1000 * 24)
      return date
    }
  }
]
</script>

Key Points

• Use v-model for selected date
• Multiple types: date, datetime, daterange, etc.
• Configure format and value-format
• Support shortcuts
• Use Day.js for date handling

Dialog Component

官方文档: https://element-plus.org/en-US/component/dialog.html

Instructions

This example demonstrates the Dialog component in Element Plus.

Key Concepts

• Dialog visibility
• Dialog content
• Dialog actions
• Dialog events
• Dialog methods

Example: Basic Dialog

<template>
  <el-button @click="dialogVisible = true">Open Dialog</el-button>
  <el-dialog v-model="dialogVisible" title="Dialog Title">
    <span>Dialog Content</span>
    <template #footer>
      <el-button @click="dialogVisible = false">Cancel</el-button>
      <el-button type="primary" @click="dialogVisible = false">Confirm</el-button>
    </template>
  </el-dialog>
</template>

<script setup>
import { ref } from 'vue'

const dialogVisible = ref(false)
</script>

Example: Dialog with Form

<template>
  <el-button @click="dialogVisible = true">Open Dialog</el-button>
  <el-dialog v-model="dialogVisible" title="Form Dialog" width="500px">
    <el-form :model="form" label-width="100px">
      <el-form-item label="Name">
        <el-input v-model="form.name" />
      </el-form-item>
      <el-form-item label="Email">
        <el-input v-model="form.email" />
      </el-form-item>
    </el-form>
    <template #footer>
      <el-button @click="dialogVisible = false">Cancel</el-button>
      <el-button type="primary" @click="handleSubmit">Submit</el-button>
    </template>
  </el-dialog>
</template>

<script setup>
import { ref } from 'vue'

const dialogVisible = ref(false)
const form = ref({
  name: '',
  email: ''
})

const handleSubmit = () => {
  console.log('Form:', form.value)
  dialogVisible.value = false
}
</script>

Example: Dialog Methods

<template>
  <el-button @click="openDialog">Open Dialog</el-button>
</template>

<script setup>
import { ElMessageBox } from 'element-plus'

const openDialog = () => {
  ElMessageBox.confirm('Are you sure?', 'Confirm', {
    confirmButtonText: 'OK',
    cancelButtonText: 'Cancel',
    type: 'warning'
  }).then(() => {
    console.log('Confirmed')
  }).catch(() => {
    console.log('Cancelled')
  })
}
</script>

Key Points

• Control visibility with v-model
• Use title prop for dialog title
• Customize footer with footer slot
• Support form inside dialog
• Use ElMessageBox for programmatic dialogs

Form Component

官方文档: https://element-plus.org/en-US/component/form.html

Instructions

This example demonstrates the Form component in Element Plus.

Key Concepts

• Form structure
• Form validation
• Form rules
• Form submission
• Form fields

Example: Basic Form

<template>
  <el-form :model="form" label-width="120px">
    <el-form-item label="Name">
      <el-input v-model="form.name" />
    </el-form-item>
    <el-form-item label="Email">
      <el-input v-model="form.email" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleSubmit">Submit</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup>
import { ref } from 'vue'

const form = ref({
  name: '',
  email: ''
})

const handleSubmit = () => {
  console.log('Form:', form.value)
}
</script>

Example: Form Validation

<template>
  <el-form
    ref="formRef"
    :model="form"
    :rules="rules"
    label-width="120px"
  >
    <el-form-item label="Name" prop="name">
      <el-input v-model="form.name" />
    </el-form-item>
    <el-form-item label="Email" prop="email">
      <el-input v-model="form.email" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleSubmit">Submit</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup>
import { ref } from 'vue'

const formRef = ref()
const form = ref({
  name: '',
  email: ''
})

const rules = {
  name: [
    { required: true, message: 'Please input name', trigger: 'blur' }
  ],
  email: [
    { required: true, message: 'Please input email', trigger: 'blur' },
    { type: 'email', message: 'Please input valid email', trigger: 'blur' }
  ]
}

const handleSubmit = async () => {
  await formRef.value.validate((valid) => {
    if (valid) {
      console.log('Form valid:', form.value)
    }
  })
}
</script>

Example: Form Layout

<template>
  <el-form :model="form" label-position="top">
    <el-row :gutter="20">
      <el-col :span="12">
        <el-form-item label="Name">
          <el-input v-model="form.name" />
        </el-form-item>
      </el-col>
      <el-col :span="12">
        <el-form-item label="Email">
          <el-input v-model="form.email" />
        </el-form-item>
      </el-col>
    </el-row>
  </el-form>
</template>

Key Points

• Use :model for form data
• Configure :rules for validation
• Use prop for form-item validation
• Handle form submission
• Support multiple layouts

Input Component

官方文档: https://element-plus.org/en-US/component/input.html

Instructions

This example demonstrates the Input component in Element Plus.

Key Concepts

• Input types
• Input sizes
• Input states
• Input events
• Input validation

Example: Basic Input

<template>
  <el-input v-model="input" placeholder="Please input" />
</template>

<script setup>
import { ref } from 'vue'
const input = ref('')
</script>

Example: Input Types

<template>
  <el-input v-model="text" type="text" />
  <el-input v-model="password" type="password" show-password />
  <el-input v-model="textarea" type="textarea" :rows="4" />
</template>

<script setup>
import { ref } from 'vue'
const text = ref('')
const password = ref('')
const textarea = ref('')
</script>

Example: Input Sizes

<template>
  <el-input v-model="input1" size="large" />
  <el-input v-model="input2" size="default" />
  <el-input v-model="input3" size="small" />
</template>

Example: Input States

<template>
  <el-input v-model="input" disabled />
  <el-input v-model="input" readonly />
  <el-input v-model="input" clearable />
</template>

Example: Input with Prefix/Suffix

<template>
  <el-input v-model="input1">
    <template #prefix>
      <el-icon><Search /></el-icon>
    </template>
  </el-input>
  <el-input v-model="input2">
    <template #suffix>
      <el-icon><Calendar /></el-icon>
    </template>
  </el-input>
</template>

Example: Input Events

<template>
  <el-input
    v-model="input"
    @input="handleInput"
    @change="handleChange"
    @focus="handleFocus"
    @blur="handleBlur"
  />
</template>

<script setup>
import { ref } from 'vue'
const input = ref('')

const handleInput = (value) => {
  console.log('Input:', value)
}
const handleChange = (value) => {
  console.log('Change:', value)
}
const handleFocus = () => {
  console.log('Focus')
}
const handleBlur = () => {
  console.log('Blur')
}
</script>

Key Points

• Use v-model for two-way binding
• Support multiple input types
• Support disabled, readonly, clearable
• Prefix and suffix slots
• Multiple event handlers

Message Component

官方文档: https://element-plus.org/en-US/component/message.html

Instructions

This example demonstrates the Message component in Element Plus.

Key Concepts

• Message types
• Message duration
• Message positioning
• Message methods

Example: Message API

<template>
  <el-button @click="showMessage">Show Message</el-button>
</template>

<script setup>
import { ElMessage } from 'element-plus'

const showMessage = () => {
  ElMessage.success('Success message')
}
</script>

Example: Message Types

<script setup>
import { ElMessage } from 'element-plus'

// Success
ElMessage.success('Success message')

// Warning
ElMessage.warning('Warning message')

// Error
ElMessage.error('Error message')

// Info
ElMessage.info('Info message')
</script>

Example: Message Options

<script setup>
import { ElMessage } from 'element-plus'

ElMessage({
  message: 'Custom message',
  type: 'success',
  duration: 3000,
  showClose: true,
  center: true
})
</script>

Example: Message Positioning

<script setup>
import { ElMessage } from 'element-plus'

ElMessage({
  message: 'Top message',
  position: 'top'
})

ElMessage({
  message: 'Top-right message',
  position: 'top-right'
})
</script>

Key Points

• Use ElMessage API for programmatic messages
• Multiple types: success, warning, error, info
• Configure duration and position
• Auto-close by default
• Support custom message content

Components Overview

官方文档: https://element-plus.org/en-US/component/overview.html

Instructions

This example provides an overview of Element Plus components.

Key Concepts

• Component categories
• Component list
• Component usage
• Component features

Example: Component Categories

Basic Components (基础组件):

• Button, Link, Icon

Form Components (表单组件):

• Input, Textarea, Select, Switch, Checkbox, Radio, DatePicker, TimePicker, Upload, Rate, ColorPicker, Transfer, Form

Data Display (数据展示):

• Table, Tag, Progress, Tree, Pagination, Badge, Avatar, Skeleton, Empty, Descriptions, Result, Statistic

Navigation (导航):

• NavMenu, Tabs, Breadcrumb, PageHeader, Affix, Backtop

Feedback (反馈):

• Alert, Loading, Message, MessageBox, Notification, Popover, Tooltip, Popconfirm, Drawer, Dialog

Layout (布局):

• Row, Col, Container, Aside, Main, Header, Footer

Others (其他):

• Divider, Calendar, Image, Timeline, Card, Carousel, Collapse, InfiniteScroll

Example: Component Registration

// Full import
import ElementPlus from 'element-plus'
app.use(ElementPlus)

// On-demand import
import { ElButton, ElInput } from 'element-plus'
app.component(ElButton.name, ElButton)
app.component(ElInput.name, ElInput)

Key Points

• 60+ components available
• Organized by category
• Support full import and on-demand import
• TypeScript support
• Consistent API design

Select Component

官方文档: https://element-plus.org/en-US/component/select.html

Instructions

This example demonstrates the Select component in Element Plus.

Key Concepts

• Select options
• Select multiple
• Select filtering
• Select events

Example: Basic Select

<template>
  <el-select v-model="value" placeholder="Select">
    <el-option label="Option 1" value="1" />
    <el-option label="Option 2" value="2" />
    <el-option label="Option 3" value="3" />
  </el-select>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('')
</script>

Example: Select with Options Array

<template>
  <el-select v-model="value" placeholder="Select">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('')
const options = ref([
  { label: 'Option 1', value: '1' },
  { label: 'Option 2', value: '2' },
  { label: 'Option 3', value: '3' }
])
</script>

Example: Multiple Select

<template>
  <el-select v-model="value" multiple placeholder="Select multiple">
    <el-option label="Option 1" value="1" />
    <el-option label="Option 2" value="2" />
    <el-option label="Option 3" value="3" />
  </el-select>
</template>

<script setup>
import { ref } from 'vue'

const value = ref([])
</script>

Example: Filterable Select

<template>
  <el-select
    v-model="value"
    filterable
    placeholder="Search and select"
  >
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value"
    />
  </el-select>
</template>

Example: Select Events

<template>
  <el-select
    v-model="value"
    @change="handleChange"
    @visible-change="handleVisibleChange"
  >
    <el-option label="Option 1" value="1" />
    <el-option label="Option 2" value="2" />
  </el-select>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('')

const handleChange = (val) => {
  console.log('Changed:', val)
}

const handleVisibleChange = (visible) => {
  console.log('Visible:', visible)
}
</script>

Key Points

• Use v-model for selected value
• Use el-option for options
• Support multiple selection
• Enable filtering with filterable
• Handle change and visible-change events

Table Component

官方文档: https://element-plus.org/en-US/component/table.html

Instructions

This example demonstrates the Table component in Element Plus.

Key Concepts

• Table data
• Table columns
• Table selection
• Table sorting
• Table filtering
• Table pagination

Example: Basic Table

<template>
  <el-table :data="tableData">
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="email" label="Email" />
    <el-table-column prop="age" label="Age" />
  </el-table>
</template>

<script setup>
import { ref } from 'vue'

const tableData = ref([
  { name: 'John', email: 'john@example.com', age: 25 },
  { name: 'Jane', email: 'jane@example.com', age: 30 }
])
</script>

Example: Table with Selection

<template>
  <el-table
    :data="tableData"
    @selection-change="handleSelectionChange"
  >
    <el-table-column type="selection" width="55" />
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="email" label="Email" />
  </el-table>
</template>

<script setup>
import { ref } from 'vue'

const tableData = ref([
  { name: 'John', email: 'john@example.com' },
  { name: 'Jane', email: 'jane@example.com' }
])

const handleSelectionChange = (selection) => {
  console.log('Selected:', selection)
}
</script>

Example: Table with Sorting

<template>
  <el-table :data="tableData" default-sort="{ prop: 'age', order: 'ascending' }">
    <el-table-column prop="name" label="Name" sortable />
    <el-table-column prop="age" label="Age" sortable />
  </el-table>
</template>

Example: Table with Filtering

<template>
  <el-table :data="tableData">
    <el-table-column prop="status" label="Status" :filters="filters" :filter-method="filterMethod">
      <template #default="{ row }">
        <el-tag :type="row.status === 'active' ? 'success' : 'info'">
          {{ row.status }}
        </el-tag>
      </template>
    </el-table-column>
  </el-table>
</template>

<script setup>
import { ref } from 'vue'

const tableData = ref([
  { name: 'John', status: 'active' },
  { name: 'Jane', status: 'inactive' }
])

const filters = [
  { text: 'Active', value: 'active' },
  { text: 'Inactive', value: 'inactive' }
]

const filterMethod = (value, row) => {
  return row.status === value
}
</script>

Example: Table with Pagination

<template>
  <el-table :data="paginatedData">
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="email" label="Email" />
  </el-table>
  <el-pagination
    v-model:current-page="currentPage"
    v-model:page-size="pageSize"
    :total="total"
    layout="total, sizes, prev, pager, next, jumper"
    @size-change="handleSizeChange"
    @current-change="handleCurrentChange"
  />
</template>

<script setup>
import { ref, computed } from 'vue'

const tableData = ref([
  { name: 'John', email: 'john@example.com' },
  { name: 'Jane', email: 'jane@example.com' },
  // ... more data
])

const currentPage = ref(1)
const pageSize = ref(10)
const total = ref(100)

const paginatedData = computed(() => {
  const start = (currentPage.value - 1) * pageSize.value
  const end = start + pageSize.value
  return tableData.value.slice(start, end)
})

const handleSizeChange = (val) => {
  pageSize.value = val
}

const handleCurrentChange = (val) => {
  currentPage.value = val
}
</script>

Key Points

• Use :data for table data
• Define columns with el-table-column
• Support selection, sorting, filtering
• Use pagination for large datasets
• Customize columns with slots

Design Guidelines

Instructions

This example covers Element Plus design guidelines and principles.

Key Concepts

• Design principles
• Color system
• Typography
• Spacing
• Components

Example: Design Principles

Element Plus follows Element Design principles:

• Consistency: Consistent design language
• Feedback: Clear user feedback
• Efficiency: Efficient user experience
• Controllability: User control

Example: Color System

/* Primary Color */
--el-color-primary: #409eff;

/* Success Color */
--el-color-success: #67c23a;

/* Warning Color */
--el-color-warning: #e6a23c;

/* Danger Color */
--el-color-danger: #f56c6c;

/* Info Color */
--el-color-info: #909399;

Example: Typography

<template>
  <h1>Heading 1</h1>
  <h2>Heading 2</h2>
  <h3>Heading 3</h3>
  <p>Body text</p>
</template>

Example: Spacing

Element Plus uses consistent spacing scale:

• xs: 4px
• sm: 8px
• md: 16px
• lg: 24px
• xl: 32px

Key Points

• Follow Element Design principles
• Use consistent colors
• Apply proper typography
• Use spacing scale
• Maintain design consistency

Global Configuration

Instructions

This example demonstrates how to configure Element Plus globally.

Key Concepts

• Global config options
• ConfigProvider
• Size configuration
• z-index configuration

Example: Global Config

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, {
  size: 'large',
  zIndex: 3000,
  locale: zhCn
})
app.mount('#app')

Example: Using ConfigProvider

<template>
  <el-config-provider :size="size" :z-index="zIndex" :locale="locale">
    <el-button>Button</el-button>
    <el-input v-model="input" />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

const size = ref('default')
const zIndex = ref(3000)
const locale = ref(zhCn)
const input = ref('')
</script>

Example: Size Configuration

<template>
  <el-config-provider :size="size">
    <el-button>Button</el-button>
    <el-input v-model="input" />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'

const size = ref('default') // 'large' | 'default' | 'small'
</script>

Example: z-index Configuration

<template>
  <el-config-provider :z-index="zIndex">
    <el-dialog v-model="visible" title="Dialog">
      Content
    </el-dialog>
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'

const zIndex = ref(3000)
const visible = ref(false)
</script>

Key Points

• Configure globally via app.use()
• Use ConfigProvider for component-level config
• Size: 'large' | 'default' | 'small'
• z-index: number (default: 3000)
• Locale: locale object

Internationalization (i18n)

Instructions

This example demonstrates how to configure internationalization in Element Plus.

Key Concepts

• Locale configuration
• Language switching
• DatePicker locale
• ConfigProvider

Example: Basic i18n Setup

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
import en from 'element-plus/dist/locale/en.mjs'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, {
  locale: zhCn
})
app.mount('#app')

Example: Using ConfigProvider

<template>
  <el-config-provider :locale="locale">
    <el-date-picker v-model="date" />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
import en from 'element-plus/dist/locale/en.mjs'

const locale = ref(zhCn)
const date = ref('')
</script>

Example: Language Switching

<template>
  <el-config-provider :locale="currentLocale">
    <el-select v-model="language" @change="handleLanguageChange">
      <el-option label="中文" value="zh-cn" />
      <el-option label="English" value="en" />
    </el-select>
    <el-date-picker v-model="date" />
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
import en from 'element-plus/dist/locale/en.mjs'

const language = ref('zh-cn')
const currentLocale = ref(zhCn)
const date = ref('')

const handleLanguageChange = (value) => {
  currentLocale.value = value === 'zh-cn' ? zhCn : en
}
</script>

Example: Available Locales

import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
import en from 'element-plus/dist/locale/en.mjs'
import es from 'element-plus/dist/locale/es.mjs'
import fr from 'element-plus/dist/locale/fr.mjs'
import ja from 'element-plus/dist/locale/ja.mjs'
import ko from 'element-plus/dist/locale/ko.mjs'

Key Points

• Import locale files
• Configure locale globally or per component
• Use ConfigProvider for locale
• Support multiple languages
• DatePicker uses Day.js locale

Installation

Instructions

This example demonstrates how to install Element Plus in a Vue 3 project.

Key Concepts

• Package installation
• Full import
• On-demand import
• CDN import
• Compatibility

Example: Package Installation

# Using npm
npm install element-plus

# Using yarn
yarn add element-plus

# Using pnpm
pnpm add element-plus

Example: Full Import

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

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

Example: On-Demand Import

// main.js
import { createApp } from 'vue'
import { ElButton, ElInput } from 'element-plus'
import 'element-plus/es/components/button/style/css'
import 'element-plus/es/components/input/style/css'
import App from './App.vue'

const app = createApp(App)
app.component(ElButton.name, ElButton)
app.component(ElInput.name, ElInput)
app.mount('#app')

Example: CDN Import

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/element-plus/dist/index.css" />
</head>
<body>
  <div id="app"></div>
  <script src="https://unpkg.com/vue@next"></script>
  <script src="https://unpkg.com/element-plus"></script>
  <script>
    const { createApp } = Vue
    const app = createApp({})
    app.use(ElementPlus)
    app.mount('#app')
  </script>
</body>
</html>

Example: Auto Import with unplugin-vue-components

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})

Key Points

• Install element-plus package
• Choose between full import or on-demand import
• Import CSS styles
• Use app.use() for full import
• Use auto-import plugins for better DX
• Element Plus requires Vue 3

Quick Start

Instructions

This example provides a quick start guide for Element Plus.

Key Concepts

• Basic setup
• First component
• Global configuration
• Component usage

Example: Basic Setup

<template>
  <el-button type="primary">Button</el-button>
</template>

<script setup>
// Component is auto-imported if using unplugin-vue-components
</script>

Example: With Options API

<template>
  <el-button type="primary" @click="handleClick">
    Click Me
  </el-button>
</template>

<script>
export default {
  methods: {
    handleClick() {
      console.log('Button clicked')
    }
  }
}
</script>

Example: With Composition API

<template>
  <el-button type="primary" @click="handleClick">
    Click Me
  </el-button>
</template>

<script setup>
const handleClick = () => {
  console.log('Button clicked')
}
</script>

Example: Global Configuration

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, {
  size: 'large',
  zIndex: 3000
})
app.mount('#app')

Example: Using ConfigProvider

<template>
  <el-config-provider :locale="locale" :size="size">
    <el-button>Button</el-button>
  </el-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import zhCn from 'element-plus/dist/locale/zh-cn.mjs'

const locale = ref(zhCn)
const size = ref('default')
</script>

Key Points

• Use el- prefix for components
• Support both Options API and Composition API
• Configure globally or per component
• Use ConfigProvider for locale and size
• Import styles for components

Theme Customization

Instructions

This example demonstrates how to customize Element Plus theme.

Key Concepts

• CSS variables
• SCSS variables
• Theme builder
• Color customization

Example: Using CSS Variables

<template>
  <el-button type="primary">Button</el-button>
</template>

<style>
:root {
  --el-color-primary: #409eff;
  --el-color-success: #67c23a;
  --el-color-warning: #e6a23c;
  --el-color-danger: #f56c6c;
  --el-color-info: #909399;
}
</style>

Example: SCSS Variables

// variables.scss
$--color-primary: #409eff;
$--color-success: #67c23a;
$--color-warning: #e6a23c;
$--color-danger: #f56c6c;
$--color-info: #909399;

Example: Import Custom Theme

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import './theme/index.css'
import App from './App.vue'

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

Example: Component-Level Customization

<template>
  <el-button class="custom-button">Button</el-button>
</template>

<style scoped>
.custom-button {
  --el-button-bg-color: #409eff;
  --el-button-text-color: #fff;
}
</style>

Key Points

• Use CSS variables for customization
• Override theme variables
• Use SCSS for advanced customization
• Component-level customization supported
• Use theme builder for visual customization

Component Usage Templates

Button Usage

<template>
  <el-button type="primary" @click="handleClick">
    Click Me
  </el-button>
</template>

<script setup>
const handleClick = () => {
  console.log('Clicked')
}
</script>

Form Usage

<template>
  <el-form :model="form" :rules="rules" ref="formRef">
    <el-form-item label="Name" prop="name">
      <el-input v-model="form.name" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleSubmit">Submit</el-button>
    </el-form-item>
  </el-form>
</template>

<script setup>
import { ref } from 'vue'

const formRef = ref()
const form = ref({
  name: ''
})

const rules = {
  name: [
    { required: true, message: 'Please input name', trigger: 'blur' }
  ]
}

const handleSubmit = async () => {
  await formRef.value.validate((valid) => {
    if (valid) {
      console.log('Form:', form.value)
    }
  })
}
</script>

Table Usage

<template>
  <el-table :data="tableData">
    <el-table-column prop="name" label="Name" />
    <el-table-column prop="email" label="Email" />
  </el-table>
</template>

<script setup>
import { ref } from 'vue'

const tableData = ref([
  { name: 'John', email: 'john@example.com' },
  { name: 'Jane', email: 'jane@example.com' }
])
</script>

Dialog Usage

<template>
  <el-button @click="dialogVisible = true">Open Dialog</el-button>
  <el-dialog v-model="dialogVisible" title="Dialog">
    <span>Dialog Content</span>
  </el-dialog>
</template>

<script setup>
import { ref } from 'vue'

const dialogVisible = ref(false)
</script>

Installation Templates

npm Installation

npm install element-plus

Full Import

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

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

On-Demand Import

// main.js
import { createApp } from 'vue'
import { ElButton, ElInput } from 'element-plus'
import 'element-plus/es/components/button/style/css'
import 'element-plus/es/components/input/style/css'
import App from './App.vue'

const app = createApp(App)
app.component(ElButton.name, ElButton)
app.component(ElInput.name, ElInput)
app.mount('#app')

Auto Import with unplugin-vue-components

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})

CDN Import

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/element-plus/dist/index.css" />
</head>
<body>
  <div id="app"></div>
  <script src="https://unpkg.com/vue@next"></script>
  <script src="https://unpkg.com/element-plus"></script>
  <script>
    const { createApp } = Vue
    const app = createApp({})
    app.use(ElementPlus)
    app.mount('#app')
  </script>
</body>
</html>

Project Setup Templates

Vite Project Setup

# Create Vite project
npm create vite@latest my-app -- --template vue

# Install dependencies
cd my-app
npm install
npm install element-plus

# Install auto-import plugins
npm install -D unplugin-vue-components unplugin-auto-import

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()],
    }),
    Components({
      resolvers: [ElementPlusResolver()],
    }),
  ],
})

Vue CLI Project Setup

# Create Vue CLI project
vue create my-app

# Install Element Plus
cd my-app
npm install element-plus

// main.js
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

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

Nuxt 3 Project Setup

# Create Nuxt 3 project
npx nuxi@latest init my-app

# Install Element Plus
cd my-app
npm install element-plus

// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'

export default defineNuxtConfig({
  css: ['element-plus/dist/index.css'],
  build: {
    transpile: ['element-plus']
  }
})