el-tabs

Element Plus Tabs Component

Divide data collections which are related yet belong to different types.

When to Invoke

Invoke this skill when:

User needs to create tabbed content
User wants to add/close tabs dynamically
User needs card or border-card style tabs
User wants to position tabs (top, left, right, bottom)
User asks about tab switching with confirmation

Features

Multiple Styles: Default, card, border-card
Tab Position: Top, bottom, left, right
Dynamic Tabs: Add and remove tabs
Custom Labels: Custom content in tab labels
Lazy Rendering: Lazy load tab content
Before Leave Hook: Confirm before switching tabs

API Reference

Tabs Attributes

Name	Description	Type	Default
model-value / v-model	binding value, name of selected tab	`string \| number`	—
default-value	The value of the tab that should be active when initially rendered	`string \| number`	—
type	type of Tab	`'' \| 'card' \| 'border-card'`	''
closable	whether Tab is closable	`boolean`	false
addable	whether Tab is addable	`boolean`	false
editable	whether Tab is addable and closable	`boolean`	false
tab-position	position of tabs	`'top' \| 'right' \| 'bottom' \| 'left'`	top
stretch	whether width fits container	`boolean`	false
before-leave	hook before switching tab	`(activeName, oldActiveName) => Awaitable<void \| boolean>`	() => true
tabindex	tabs tabindex	`string \| number`	0

Tabs Events

Name	Description	Parameters
tab-click	triggers when a tab is clicked	`(pane, ev)`
tab-change	triggers when activeName changes	`(name)`
tab-remove	triggers when remove button is clicked	`(name)`
tab-add	triggers when add button is clicked	`()`
edit	triggers when add or remove is clicked	`(paneName, action)`

Tabs Slots

Name	Description	Subtags
default	customize default content	Tab-pane
add-icon	customize add button icon	—

Tabs Exposes

Name	Description	Type
currentName	current active pane name	`Ref<TabPaneName>`
tabNavRef	tab-nav component instance	`Ref<TabNavInstance \| undefined>`

Tab-pane Attributes

Name	Description	Type	Default
label	title of the tab	`string`	''
disabled	whether Tab is disabled	`boolean`	false
name	identifier corresponding to Tabs name	`string \| number`	—
closable	whether Tab is closable	`boolean`	false
lazy	whether Tab is lazily rendered	`boolean`	false

Tab-pane Slots

Name	Description
default	Tab-pane's content
label	Tab-pane's label

Usage Examples

Basic Usage

<template>
  <el-tabs v-model="activeName" @tab-click="handleClick">
    <el-tab-pane label="User" name="first">User</el-tab-pane>
    <el-tab-pane label="Config" name="second">Config</el-tab-pane>
    <el-tab-pane label="Role" name="third">Role</el-tab-pane>
    <el-tab-pane label="Task" name="fourth">Task</el-tab-pane>
  </el-tabs>
</template>

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

const activeName = ref('first')

const handleClick = (tab, event) => {
  console.log(tab, event)
}
</script>

Card Style

<template>
  <el-tabs v-model="activeName" type="card">
    <el-tab-pane label="User" name="first">User</el-tab-pane>
    <el-tab-pane label="Config" name="second">Config</el-tab-pane>
    <el-tab-pane label="Role" name="third">Role</el-tab-pane>
  </el-tabs>
</template>

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

const activeName = ref('first')
</script>

Border Card

<template>
  <el-tabs type="border-card">
    <el-tab-pane label="User">User</el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
    <el-tab-pane label="Role">Role</el-tab-pane>
  </el-tabs>
</template>

Tab Position

<template>
  <el-radio-group v-model="tabPosition" style="margin-bottom: 32px">
    <el-radio-button value="top">Top</el-radio-button>
    <el-radio-button value="right">Right</el-radio-button>
    <el-radio-button value="bottom">Bottom</el-radio-button>
    <el-radio-button value="left">Left</el-radio-button>
  </el-radio-group>

  <el-tabs :tab-position="tabPosition" style="height: 200px">
    <el-tab-pane label="User">User</el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
    <el-tab-pane label="Role">Role</el-tab-pane>
    <el-tab-pane label="Task">Task</el-tab-pane>
  </el-tabs>
</template>

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

const tabPosition = ref('left')
</script>

Custom Tab Label

<template>
  <el-tabs type="border-card">
    <el-tab-pane>
      <template #label>
        <span>
          <el-icon><Calendar /></el-icon>
          Route
        </span>
      </template>
      Route
    </el-tab-pane>
    <el-tab-pane label="Message">Message</el-tab-pane>
    <el-tab-pane label="Config">Config</el-tab-pane>
  </el-tabs>
</template>

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

Dynamic Tabs

<template>
  <el-tabs
    v-model="editableTabsValue"
    type="card"
    editable
    @edit="handleTabsEdit"
  >
    <el-tab-pane
      v-for="item in editableTabs"
      :key="item.name"
      :label="item.title"
      :name="item.name"
    >
      {{ item.content }}
    </el-tab-pane>
  </el-tabs>
</template>

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

let tabIndex = 2
const editableTabsValue = ref('2')
const editableTabs = ref([
  { title: 'Tab 1', name: '1', content: 'Tab 1 content' },
  { title: 'Tab 2', name: '2', content: 'Tab 2 content' }
])

const handleTabsEdit = (targetName, action) => {
  if (action === 'add') {
    const newTabName = `${++tabIndex}`
    editableTabs.value.push({
      title: 'New Tab',
      name: newTabName,
      content: 'New Tab content'
    })
    editableTabsValue.value = newTabName
  } else if (action === 'remove') {
    const tabs = editableTabs.value
    let activeName = editableTabsValue.value
    if (activeName === targetName) {
      tabs.forEach((tab, index) => {
        if (tab.name === targetName) {
          const nextTab = tabs[index + 1] || tabs[index - 1]
          if (nextTab) {
            activeName = nextTab.name
          }
        }
      })
    }
    editableTabsValue.value = activeName
    editableTabs.value = tabs.filter((tab) => tab.name !== targetName)
  }
}
</script>

Before Leave Hook

<template>
  <el-tabs v-model="activeName" :before-leave="beforeLeave">
    <el-tab-pane label="User" name="first">User</el-tab-pane>
    <el-tab-pane label="Config" name="second">Config</el-tab-pane>
  </el-tabs>
</template>

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

const activeName = ref('first')

const beforeLeave = async (activeName, oldActiveName) => {
  if (oldActiveName === 'first') {
    const confirmed = await ElMessageBox.confirm(
      'Are you sure you want to leave? Unsaved changes will be lost.',
      'Warning',
      { type: 'warning' }
    ).catch(() => false)
    return confirmed
  }
  return true
}
</script>

Lazy Loading

<template>
  <el-tabs v-model="activeName">
    <el-tab-pane label="Tab 1" name="1">Content 1</el-tab-pane>
    <el-tab-pane label="Tab 2" name="2" lazy>
      <!-- This content will only be rendered when tab is active -->
      <ExpensiveComponent />
    </el-tab-pane>
  </el-tabs>
</template>

Custom Add Button Icon

<template>
  <el-tabs type="card" addable>
    <template #add-icon>
      <el-icon><Plus /></el-icon>
    </template>
    <el-tab-pane label="Tab 1">Content 1</el-tab-pane>
    <el-tab-pane label="Tab 2">Content 2</el-tab-pane>
  </el-tabs>
</template>

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

Common Issues

1. Tab Content Not Updating

Use :key on tab-pane for dynamic content:

<el-tab-pane :key="tabKey" :label="label">
  {{ content }}
</el-tab-pane>

2. Height Issues with Left/Right Position

Set a fixed height:

<el-tabs tab-position="left" style="height: 400px">
  <!-- tabs -->
</el-tabs>

3. Tab Not Switching

Ensure v-model value matches tab name:

<el-tabs v-model="activeName">
  <el-tab-pane name="first">  <!-- activeName should be 'first' -->
</el-tabs>

Best Practices

Use lazy loading: Use lazy for expensive tab content
Unique names: Ensure each tab-pane has a unique name
Before leave hook: Use before-leave for unsaved changes warning
Card type for dynamic: Use card type when adding/removing tabs
Consistent styling: Use consistent tab type throughout the app