tusen-ai · Nakus0426 · Sep 24, 2025 · Sep 25, 2025 · Sep 25, 2025
diff --git a/CHANGELOG.en-US.md b/CHANGELOG.en-US.md
@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## NEXT_VERSION
+
+`NEXT_VERSION`
+
+### Features
+
+- `n-avatar-group` adds `cascading` prop, closes [#7227](https://github.com/tusen-ai/naive-ui/issues/7227).
+
 ## 2.43.1
 
 `2025-09-15`

diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
@@ -1,5 +1,13 @@
 # CHANGELOG
 
+## NEXT_VERSION
+
+`NEXT_VERSION`
+
+### Features
+
+- `n-avatar-group` 增加 `cascading` 属性，关闭 [#7227](https://github.com/tusen-ai/naive-ui/issues/7227)
+
 ## 2.43.1
 
 `2025-09-15`

diff --git a/src/avatar-group/src/AvatarGroup.tsx b/src/avatar-group/src/AvatarGroup.tsx
@@ -8,12 +8,7 @@ import type {
   AvatarGroupOption,
   AvatarGroupRestSlotProps
 } from './public-types'
-import {
-  computed,
-  defineComponent,
-  h,
-  provide
-} from 'vue'
+import { computed, defineComponent, h, provide } from 'vue'
 import { useConfig, useTheme } from '../../_mixins'
 import { useRtl } from '../../_mixins/use-rtl'
 import NAvatar from '../../avatar/src/Avatar'
@@ -25,6 +20,8 @@ export interface AvatarGroupInjection {
   size?: Size | undefined
 }
 
+export type CascadingDirection = 'left-up' | 'right-up'
+
 export const avatarGroupProps = {
   ...(useTheme.props as ThemeProps<AvatarGroupTheme>),
   max: Number,
@@ -35,7 +32,11 @@ export const avatarGroupProps = {
   },
   vertical: Boolean,
   expandOnHover: Boolean,
-  size: [String, Number] as PropType<Size | undefined>
+  size: [String, Number] as PropType<Size | undefined>,
+  cascading: {
+    type: String as PropType<CascadingDirection>,
+    default: 'left-up'
+  }
 } as const
 
 export type AvatarGroupProps = ExtractPublicPropTypes<typeof avatarGroupProps>
@@ -93,7 +94,8 @@ export default defineComponent({
       displayedOptions: displayedOptionsRef,
       cssVars: computed(() => {
         return {
-          '--n-gap': mergedThemeRef.value.self.gap
+          '--n-gap': mergedThemeRef.value.self.gap,
+          '--n-avatar-total': displayedOptionsRef.value.length
         }
       })
     }
@@ -113,19 +115,22 @@ export default defineComponent({
           this.rtlEnabled && `${mergedClsPrefix}-avatar-group--rtl`,
           this.vertical && `${mergedClsPrefix}-avatar-group--vertical`,
           this.expandOnHover
-          && `${mergedClsPrefix}-avatar-group--expand-on-hover`
+          && `${mergedClsPrefix}-avatar-group--expand-on-hover`,
+          this.cascading
+          && `${mergedClsPrefix}-avatar-group--cascading-${this.cascading}`
         ]}
         style={this.cssVars}
         role="group"
       >
-        {displayedOptions.map((option) => {
+        {displayedOptions.map((option, index) => {
           return $slots.avatar ? (
             $slots.avatar({ option })
           ) : (
             <NAvatar
               src={option.src}
               theme={mergedTheme.peers.Avatar}
               themeOverrides={mergedTheme.peerOverrides.Avatar}
+              style={{ '--n-avatar-index': index }}
             />
           )
         })}

diff --git a/src/avatar-group/src/generic-public-types.ts b/src/avatar-group/src/generic-public-types.ts
@@ -17,6 +17,7 @@ interface ResolvableAvatarGroupProps<
   size?: Size
   max?: number
   maxStyle?: string | CSSProperties
+  cascading?: 'left-up' | 'right-up'
 }
 
 // eslint-disable-next-line ts/ban-ts-comment

diff --git a/src/avatar-group/src/styles/avatar-group.cssr.ts b/src/avatar-group/src/styles/avatar-group.cssr.ts
@@ -46,5 +46,19 @@ export default cB('avatar-group', `
          margin-top: var(--n-gap);
       `)
     ])
+  ]),
+  cM('cascading-left-up', [
+    cB('avatar', [
+      c('&', `
+        z-index: calc(var(--n-avatar-total, 1) - var(--n-avatar-index, 0));
+      `)
+    ])
+  ]),
+  cM('cascading-right-up', [
+    cB('avatar', [
+      c('&', `
+        z-index: calc(var(--n-avatar-index, 0) + 1);
+      `)
+    ])
   ])
 ])
diff --git a/src/avatar/demos/enUS/cascading.demo.vue b/src/avatar/demos/enUS/cascading.demo.vue
@@ -0,0 +1,32 @@
+<markdown>
+# Stacking Direction
+
+Avatar groups can have cascading stacking direction.
+</markdown>
+
+<script lang="ts" setup>
+import type { AvatarGroupOption } from 'naive-ui'
+import { NAvatarGroup } from 'naive-ui'
+
+const options: AvatarGroupOption[] = [
+  {
+    src: 'https://gw.alipayobjects.com/zos/antfincdn/aPkFc8Sj7n/method-draw-image.svg'
+  },
+  {
+    src: 'https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg'
+  },
+  {
+    src: 'https://gw.alipayobjects.com/zos/antfincdn/aPkFc8Sj7n/method-draw-image.svg'
+  },
+  {
+    src: 'https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg'
+  }
+]
+</script>
+
+<template>
+  <NFlex vertical>
+    <NAvatarGroup :options="options" cascading="left-up" />
+    <NAvatarGroup :options="options" cascading="right-up" />
+  </NFlex>
+</template>
diff --git a/src/avatar/demos/enUS/index.demo-entry.md b/src/avatar/demos/enUS/index.demo-entry.md
@@ -13,6 +13,7 @@ icon.vue
 name-size.vue
 fallback.vue
 group.vue
+cascading.vue
 lazy.vue
 v-show-debug.vue
 ```
@@ -51,6 +52,7 @@ interface AvatarGroupOption {
 
 | Name | Type | Default | Description | Version |
 | --- | --- | --- | --- | --- |
+| cascading | `'left-up' \| 'right-up'` | `left-up` | Cascading direction of avatar group. | NEXT_VERSION |
 | expand-on-hover | `boolean` | `false` | Expand on hover. | 2.37.0 |
 | max | `number` | `undefined` | Max avatar count in the group. |  |
 | max-style | `Object \| string` | `undefined` | The style of the overflow placeholder. |  |

diff --git a/src/avatar/demos/zhCN/cascading.demo.vue b/src/avatar/demos/zhCN/cascading.demo.vue
@@ -0,0 +1,32 @@
+<markdown>
+# 层叠方向
+
+头像也分上下
+</markdown>
+
+<script lang="ts" setup>
+import type { AvatarGroupOption } from 'naive-ui'
+import { NAvatarGroup } from 'naive-ui'
+
+const options: AvatarGroupOption[] = [
+  {
+    src: 'https://gw.alipayobjects.com/zos/antfincdn/aPkFc8Sj7n/method-draw-image.svg'
+  },
+  {
+    src: 'https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg'
+  },
+  {
+    src: 'https://gw.alipayobjects.com/zos/antfincdn/aPkFc8Sj7n/method-draw-image.svg'
+  },
+  {
+    src: 'https://07akioni.oss-cn-beijing.aliyuncs.com/07akioni.jpeg'
+  }
+]
+</script>
+
+<template>
+  <NFlex vertical>
+    <NAvatarGroup :options="options" cascading="left-up" />
+    <NAvatarGroup :options="options" cascading="right-up" />
+  </NFlex>
+</template>
diff --git a/src/avatar/demos/zhCN/index.demo-entry.md b/src/avatar/demos/zhCN/index.demo-entry.md
@@ -14,6 +14,7 @@ icon.vue
 name-size.vue
 fallback.vue
 group.vue
+cascading.vue
 lazy.vue
 v-show-debug.vue
 rtl-debug.vue
@@ -53,6 +54,7 @@ interface AvatarGroupOption {
 
 | 名称 | 类型 | 默认值 | 说明 | 版本 |
 | --- | --- | --- | --- | --- |
+| cascading | `'left-up' \| 'right-up'` | `left-up` | 头像的层叠方向 | NEXT_VERSION |
 | expand-on-hover | `boolean` | `false` | 悬停时展开 | 2.37.0 |
 | max | `number` | `undefined` | 组内头像显示的最大个数 |  |
 | max-style | `Object \| string` | `undefined` | 溢出标识的样式 |  |