From 7be439a53a117af76a485f11be896af4b4cec754 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E4=BA=91=E6=B8=B8=E5=90=9B?= <me@yunyoujun.cn>
Date: Sun, 23 Nov 2025 15:18:51 +0800
Subject: [PATCH] fix(components): [tabs] default-value support and update demo
 for docs (#22896)

* fix(components): [tabs] default-value support and update demo for docs

* chore: update docs/en-US/component/tabs.md

Co-authored-by: btea <2356281422@qq.com>

* fix(components): [tabs] undefined for defaultValue

---------

Co-authored-by: btea <2356281422@qq.com>
---
 docs/en-US/component/tabs.md             | 10 ++++-
 docs/examples/tabs/default-value.vue     | 47 ++++++++++++++++++++++++
 packages/components/tabs/src/tab-bar.vue | 18 +++++----
 packages/components/tabs/src/tabs.tsx    |  9 -----
 4 files changed, 66 insertions(+), 18 deletions(-)
 create mode 100644 docs/examples/tabs/default-value.vue

diff --git a/docs/en-US/component/tabs.md b/docs/en-US/component/tabs.md
index 3d7b6f39c2..82093f968f 100644
--- a/docs/en-US/component/tabs.md
+++ b/docs/en-US/component/tabs.md
@@ -83,6 +83,14 @@ tabs/customized-trigger
 
 :::
 
+## Default value
+
+:::demo
+
+tabs/default-value
+
+:::
+
 ## Tabs API
 
 ### Tabs Attributes
@@ -90,7 +98,7 @@ tabs/customized-trigger
 | Name                  | Description                                                                                                                             | Type                                                                                             | Default    |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
 | model-value / v-model | binding value, name of the selected tab, the default value is the name of first tab                                                     | ^[string] / ^[number]                                                                            | —          |
-| default-value         | initial value when `model-value` is not set                                                                                             | ^[string] / ^[number]                                                                            | —          |
+| default-value (2.11.9)| The value of the tab that should be active when initially rendered. (avoid initial transition)                                          | ^[string] / ^[number]                                                                            | —          |
 | type                  | type of Tab                                                                                                                             | ^[enum]`'' \| 'card' \| 'border-card'`                                                           | ''         |
 | closable              | whether Tab is closable                                                                                                                 | ^[boolean]                                                                                       | false      |
 | addable               | whether Tab is addable                                                                                                                  | ^[boolean]                                                                                       | false      |
diff --git a/docs/examples/tabs/default-value.vue b/docs/examples/tabs/default-value.vue
new file mode 100644
index 0000000000..96d3b7c1ae
--- /dev/null
+++ b/docs/examples/tabs/default-value.vue
@@ -0,0 +1,47 @@
+<template>
+  <el-tabs
+    v-model="activeName"
+    class="demo-tabs"
+    default-value="third"
+    @tab-click="handleClick"
+  >
+    <el-tab-pane
+      v-for="tab in tabs"
+      :key="tab.name"
+      :label="tab.label"
+      :name="tab.name"
+    >
+      default-value: third
+      <br />
+      active: {{ activeName }}
+    </el-tab-pane>
+  </el-tabs>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+
+import type { TabsPaneContext } from 'element-plus'
+
+const tabs = ref([
+  { label: 'User', name: 'first' },
+  { label: 'Config', name: 'second' },
+  { label: 'Role', name: 'third' },
+  { label: 'Task', name: 'fourth' },
+])
+
+const activeName = ref()
+
+const handleClick = (tab: TabsPaneContext, event: Event) => {
+  console.log(tab, event)
+}
+</script>
+
+<style>
+.demo-tabs > .el-tabs__content {
+  padding: 32px;
+  color: #6b778c;
+  font-size: 32px;
+  font-weight: 600;
+}
+</style>
diff --git a/packages/components/tabs/src/tab-bar.vue b/packages/components/tabs/src/tab-bar.vue
index 018cf225cb..9eb8221f08 100644
--- a/packages/components/tabs/src/tab-bar.vue
+++ b/packages/components/tabs/src/tab-bar.vue
@@ -1,6 +1,6 @@
 <template>
   <div
-    v-if="shouldRenderBar"
+    v-if="renderActiveBar"
     ref="barRef"
     :class="[ns.e('active-bar'), ns.is(rootTabs!.props.tabPosition)]"
     :style="barStyle"
@@ -30,14 +30,16 @@ const ns = useNamespace('tabs')
 
 const barRef = ref<HTMLDivElement>()
 const barStyle = ref<CSSProperties>()
-const shouldDisableInitialTransition = computed(
+/**
+ * when defaultValue is not set, the bar is always shown.
+ *
+ * when defaultValue is set, the bar will be hidden until style is calculated
+ * to avoid the bar showing in the wrong position on initial render.
+ */
+const renderActiveBar = computed(
   () =>
-    isUndefined(rootTabs.props.modelValue) &&
-    !isUndefined(rootTabs.props.defaultValue)
-)
-const shouldRenderBar = computed(
-  () =>
-    !shouldDisableInitialTransition.value || Boolean(barStyle.value?.transform)
+    isUndefined(rootTabs.props.defaultValue) ||
+    Boolean(barStyle.value?.transform)
 )
 
 const getBarStyle = (): CSSProperties => {
diff --git a/packages/components/tabs/src/tabs.tsx b/packages/components/tabs/src/tabs.tsx
index 3781eb39b4..5b1a294ab4 100644
--- a/packages/components/tabs/src/tabs.tsx
+++ b/packages/components/tabs/src/tabs.tsx
@@ -218,15 +218,6 @@ const Tabs = defineComponent({
       (modelValue) => setCurrentName(modelValue)
     )
 
-    watch(
-      () => props.defaultValue,
-      (defaultValue) => {
-        if (isUndefined(props.modelValue)) {
-          setCurrentName(defaultValue)
-        }
-      }
-    )
-
     watch(currentName, async () => {
       await nextTick()
       nav$.value?.scrollToActiveTab()