From 283fa72bc999f9dfaf3db3ad17cf7706b5702dac Mon Sep 17 00:00:00 2001
From: Zhong <cszhjh@gmail.com>
Date: Thu, 24 Jul 2025 20:03:41 +0800
Subject: [PATCH] feat(components): [cascader] add header and footer slot
 (#21486)

* feat(components): [cascader] add header and footer slot

* docs(components): [cascader] simplify the code

* docs(components): [cascader] merge header and footer example

* docs(components): [cascader] add clear case
---
 docs/en-US/component/cascader.md              |  12 ++
 .../cascader/custom-header-footer.vue         | 123 ++++++++++++++++++
 packages/components/cascader/src/cascader.vue |   6 +
 packages/theme-chalk/src/cascader.scss        |  10 ++
 packages/theme-chalk/src/common/var.scss      |  10 ++
 5 files changed, 161 insertions(+)
 create mode 100644 docs/examples/cascader/custom-header-footer.vue

diff --git a/docs/en-US/component/cascader.md b/docs/en-US/component/cascader.md
index 3561c3f12f..bb5cc3424f 100644
--- a/docs/en-US/component/cascader.md
+++ b/docs/en-US/component/cascader.md
@@ -148,6 +148,16 @@ cascader/custom-tag
 
 :::
 
+## Custom Header & Footer of the Dropdown ^(2.10.5)
+
+You can customize both the header and footer of the dropdown using slots.
+
+:::demo Use slot to customize the content.
+
+cascader/custom-header-footer
+
+:::
+
 ## Click to Select Node ^(2.10.5)
 
 Allows selecting nodes by clicking, with optional control visibility.
@@ -214,6 +224,8 @@ cascader/check-on-click-node
 | prefix ^(2.9.4)          | content as Input prefix                                                                        | —                                                         |
 | suggestion-item ^(2.9.5) | custom content for suggestion item when searching                                              | ^[object]`{ item: CascaderNode }`                         |
 | tag ^(2.10.3)            | custom tags style                                                                              | ^[object]`{ data: Tag[], deleteTag: (tag: Tag) => void }` |
+| header ^(2.10.5)         | content at the top of the dropdown                                                             | —                                                         |
+| footer ^(2.10.5)         | content at the bottom of the dropdown                                                          | —                                                         |
 
 ### Cascader Exposes
 
diff --git a/docs/examples/cascader/custom-header-footer.vue b/docs/examples/cascader/custom-header-footer.vue
new file mode 100644
index 0000000000..425f086fe8
--- /dev/null
+++ b/docs/examples/cascader/custom-header-footer.vue
@@ -0,0 +1,123 @@
+<template>
+  <div class="demo">
+    <div>
+      <p>Custom header content</p>
+      <el-cascader
+        v-model="value"
+        popper-class="custom-header"
+        :options="options"
+        :props="props"
+        clearable
+      >
+        <template #header>
+          <el-checkbox
+            v-model="checkAll"
+            :indeterminate="indeterminate"
+            @change="handleCheckAll"
+          >
+            All
+          </el-checkbox>
+        </template>
+      </el-cascader>
+    </div>
+    <div>
+      <p>Custom footer content</p>
+      <el-cascader v-model="value" :options="options" :props="props" clearable>
+        <template #footer>
+          <el-button link size="small" @click="handleClear"> Clear </el-button>
+        </template>
+      </el-cascader>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { computed, ref, watch } from 'vue'
+
+import type { CascaderOption, CheckboxValueType } from 'element-plus'
+
+const props = { multiple: true }
+const checkAll = ref(false)
+const indeterminate = ref(false)
+const value = ref<string[][]>([])
+const options = ref([
+  {
+    value: 'guide',
+    label: 'Guide',
+    children: [
+      {
+        value: 'disciplines',
+        label: 'Disciplines',
+        children: [
+          { value: 'consistency', label: 'Consistency' },
+          { value: 'feedback', label: 'Feedback' },
+          { value: 'efficiency', label: 'Efficiency' },
+          { value: 'controllability', label: 'Controllability' },
+        ],
+      },
+    ],
+  },
+])
+
+const getAllValuePaths = computed(() => {
+  const result: string[][] = []
+  const queue: { node: CascaderOption; path: string[] }[] = options.value.map(
+    (node) => ({ node, path: [node.value] })
+  )
+
+  while (queue.length > 0) {
+    const { node, path } = queue.shift()!
+    if (node.children?.length) {
+      node.children.forEach((child) => {
+        queue.push({ node: child, path: [...path, child.value as string] })
+      })
+    } else {
+      result.push(path)
+    }
+  }
+  return result
+})
+
+watch(value, (val) => {
+  if (val.length === 0) {
+    checkAll.value = false
+    indeterminate.value = false
+  } else if (val.length === getAllValuePaths.value.length) {
+    checkAll.value = true
+    indeterminate.value = false
+  } else {
+    indeterminate.value = true
+  }
+})
+
+const handleCheckAll = (val: CheckboxValueType) => {
+  indeterminate.value = false
+  value.value = val ? getAllValuePaths.value : []
+}
+
+const handleClear = () => {
+  value.value = []
+}
+</script>
+
+<style>
+.demo {
+  display: flex;
+}
+
+.demo > div {
+  flex: 1;
+  text-align: center;
+}
+
+.demo > div:not(:last-child) {
+  border-right: 1px solid var(--el-border-color);
+}
+
+.custom-header {
+  .el-checkbox {
+    display: flex;
+    height: unset;
+  }
+}
+</style>
diff --git a/packages/components/cascader/src/cascader.vue b/packages/components/cascader/src/cascader.vue
index 1028dda097..a3e9dbdb22 100644
--- a/packages/components/cascader/src/cascader.vue
+++ b/packages/components/cascader/src/cascader.vue
@@ -149,6 +149,9 @@
     </template>
 
     <template #content>
+      <div v-if="$slots.header" :class="nsCascader.e('header')" @click.stop>
+        <slot name="header" />
+      </div>
       <el-cascader-panel
         v-show="!filtering"
         ref="cascaderPanelRef"
@@ -198,6 +201,9 @@
           </li>
         </slot>
       </el-scrollbar>
+      <div v-if="$slots.footer" :class="nsCascader.e('footer')" @click.stop>
+        <slot name="footer" />
+      </div>
     </template>
   </el-tooltip>
 </template>
diff --git a/packages/theme-chalk/src/cascader.scss b/packages/theme-chalk/src/cascader.scss
index 9c6008db21..4b8e5c5264 100644
--- a/packages/theme-chalk/src/cascader.scss
+++ b/packages/theme-chalk/src/cascader.scss
@@ -154,6 +154,16 @@
     }
   }
 
+  @include e(header) {
+    padding: map.get($cascader-dropdown, 'header-padding');
+    border-bottom: map.get($cascader-dropdown, 'border');
+  }
+
+  @include e(footer) {
+    padding: map.get($cascader-dropdown, 'footer-padding');
+    border-top: map.get($cascader-dropdown, 'border');
+  }
+
   @include e(tags) {
     position: absolute;
     left: 0;
diff --git a/packages/theme-chalk/src/common/var.scss b/packages/theme-chalk/src/common/var.scss
index c72717b368..2adfea73cf 100644
--- a/packages/theme-chalk/src/common/var.scss
+++ b/packages/theme-chalk/src/common/var.scss
@@ -705,6 +705,16 @@ $cascader-search-input-margin-left: map.merge(
   $cascader-search-input-margin-left
 );
 
+$cascader-dropdown: () !default;
+$cascader-dropdown: map.merge(
+  (
+    'header-padding': 10px,
+    'footer-padding': 10px,
+    'border': 1px solid getCssVar('border-color-light'),
+  ),
+  $cascader-dropdown
+);
+
 //statistic
 // css3 var in packages/theme-chalk/src/statistic.scss
 $statistic: () !default;