# Avatar Group Overflow

## Usage

AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.

`count` is the number of hidden people, and it also builds the accessible name, so it should match what the indicator shows. The name comes from the current language, so English reads "5 more". The default slot replaces the `+N` text; short text keeps the indicator a circle and longer text widens it into a pill, so the count always fits. A `@click` handler turns the indicator into a real button that can take focus; without one it stays a static figure.

```vue
<script setup lang="ts">
import { Avatar } from '@astryx-vue/core/Avatar'
import { AvatarGroup, AvatarGroupOverflow } from '@astryx-vue/core/AvatarGroup'
</script>

<template>
  <AvatarGroup size="lg">
    <Avatar name="Alex Daniels" />
    <Avatar name="Ann Smith" />
    <AvatarGroupOverflow :count="12" />
  </AvatarGroup>
</template>
```

### Anatomy

- **Count label**: The compact `+N` or custom count text displayed inside the circular indicator.
- **Button behavior**: When `onClick` is provided, the indicator becomes an interactive button with focus and hover states.

## Best practices

| Guidance | Practice |
| --- | --- |
| Do | Pass the real hidden count to `count` so the accessible label matches the visible indicator. |
| Do | Use short custom text such as `+12` or `99+`. The indicator is a circle for short counts and grows into a pill for wider counts, so the number always fits. |
| Do | Provide `onClick` when the overflow opens a member list, popover, or detail view. |
| Don't | Do not pass custom text that disagrees with `count`; `count` continues to provide the accessible label. |
| Don't | Do not use long labels inside the indicator. Even though it stretches into a pill, a sentence in there reads as noise; put longer participant details next to the group instead. |

## Examples

Common configurations, variations, and states.

### Custom Text

Provide short custom children such as 12+ when the overflow count needs compact product-specific formatting.

```vue
<script setup lang="ts">
import { Avatar } from '@astryx-vue/core/Avatar'
import { AvatarGroup, AvatarGroupOverflow } from '@astryx-vue/core/AvatarGroup'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <Stack :gap="3" direction="vertical">
    <Text type="supporting" color="secondary">
      Team members
    </Text>
    <AvatarGroup label="Avatars" size="lg">
      <Avatar name="Alex Daniels" />
      <Avatar name="Ann Smith" />
      <Avatar name="Carol Davis" />
      <AvatarGroupOverflow :count="12">
        12+
      </AvatarGroupOverflow>
    </AvatarGroup>
  </Stack>
</template>
```

### Default Count

Use AvatarGroupOverflow without children to render the standard +N overflow count.

```vue
<script setup lang="ts">
import { Avatar } from '@astryx-vue/core/Avatar'
import { AvatarGroup, AvatarGroupOverflow } from '@astryx-vue/core/AvatarGroup'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <Stack :gap="3" direction="vertical">
    <Text type="supporting" color="secondary">
      Reviewers
    </Text>
    <AvatarGroup label="Avatars" size="lg">
      <Avatar name="Alex Daniels" />
      <Avatar name="Ann Smith" />
      <Avatar name="Carol Davis" />
      <AvatarGroupOverflow :count="2" />
    </AvatarGroup>
  </Stack>
</template>
```

### Wide Count

A wider count turns the circle into a pill: the height stays fixed and only the width grows, so a four digit number still fits.

```vue
<script setup lang="ts">
import { Avatar } from '@astryx-vue/core/Avatar'
import { AvatarGroup, AvatarGroupOverflow } from '@astryx-vue/core/AvatarGroup'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <Stack :gap="3" direction="vertical">
    <Text type="supporting" color="secondary">
      Wide count
    </Text>
    <AvatarGroup label="Avatars" size="lg">
      <Avatar name="Alex Daniels" />
      <Avatar name="Ann Smith" />
      <AvatarGroupOverflow :count="1245">
        1,245+
      </AvatarGroupOverflow>
    </AvatarGroup>
  </Stack>
</template>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` | `number` | — | Number of hidden avatars. Rendered as `+N` and also used to build the accessible name, which follows the current language (English reads `5 more`). A negative count is clamped to 0. Required. |

## Events

- `click(event: MouseEvent)`: fires when the indicator is clicked. The listener also turns the figure into a button that can take focus.

## Slots

- `default`: custom count text, such as `12+`. Falls back to `+N`. Short text keeps the indicator a circle; longer text widens it into a pill, so the count always fits.