Avatar group

Avatars stacked into a row, each separated from the next by a ring in the page colour. Past a limit of your choosing, the rest are summed up as a single disc.

Usage

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup } from 'vectis-ui'
</script>

<template>
  <!-- The separation ring takes the page background by default. This demo sits on a raised card,
       so it passes that card's colour instead. -->
  <VAvatarGroup ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
  </VAvatarGroup>
</template>

Examples

Overflow

max sets how many avatars are drawn before the rest are summed up as +N on a last disc.

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup } from 'vectis-ui'
</script>

<template>
  <VAvatarGroup :max="4" ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
    <VAvatar name="Katherine Johnson" />
    <VAvatar name="Margaret Hamilton" />
    <VAvatar name="Barbara Liskov" />
  </VAvatarGroup>
</template>

Size on the group

size on the group applies to every avatar inside, the overflow disc included. An avatar that sets a size of its own keeps it.

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup } from 'vectis-ui'
</script>

<template>
  <VAvatarGroup size="sm" :max="3" ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
    <VAvatar name="Katherine Johnson" />
  </VAvatarGroup>

  <VAvatarGroup size="lg" :max="3" ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
    <VAvatar name="Katherine Johnson" />
  </VAvatarGroup>
</template>

Compact

compact on the group takes 4px off every avatar in the row.

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup } from 'vectis-ui'
</script>

<template>
  <VAvatarGroup size="lg" ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
  </VAvatarGroup>

  <VAvatarGroup size="lg" compact ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
  </VAvatarGroup>
</template>

Custom overflow

The #overflow slot replaces the +N disc and receives count, the number of avatars being hidden.

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup } from 'vectis-ui'
</script>

<template>
  <VAvatarGroup :max="3" ring-color="var(--vectis-color-surface-raised)">
    <VAvatar name="Ada Lovelace" />
    <VAvatar name="Grace Hopper" />
    <VAvatar name="Alan Turing" />
    <VAvatar name="Katherine Johnson" />
    <VAvatar name="Margaret Hamilton" />

    <template #overflow="{ count }">
      <VAvatar color="#6d28d9" clickable :alt="`Show ${count} more members`">
        +{{ count }}
      </VAvatar>
    </template>
  </VAvatarGroup>
</template>

With tooltips

Each avatar can be wrapped in a VTooltip. The trigger has to be focusable, hence clickable here.

vue

<script setup lang="ts">
import { VAvatar, VAvatarGroup, VTooltip } from 'vectis-ui'

const members = ['Ada Lovelace', 'Grace Hopper', 'Alan Turing']
const hidden = ['Katherine Johnson', 'Margaret Hamilton']
</script>

<template>
  <VAvatarGroup :max="3" ring-color="var(--vectis-color-surface-raised)">
    <VTooltip v-for="member in [...members, ...hidden]" :key="member" :text="member">
      <template #default="{ triggerProps }">
        <VAvatar :name="member" clickable v-bind="triggerProps" />
      </template>
    </VTooltip>

    <template #overflow="{ count }">
      <VTooltip :text="hidden.join(', ')">
        <template #default="{ triggerProps }">
          <VAvatar clickable :alt="`${count} more members`" v-bind="triggerProps">
            +{{ count }}
          </VAvatar>
        </template>
      </VTooltip>
    </template>
  </VAvatarGroup>
</template>

API

Props

Prop	Type	Default
`max`	`number`	none
How many avatars to show before the remaining ones are summed up as a single "+X" disc. Left out, or set to 0, every avatar is shown.
`size`	`AvatarSize'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`
The size given to the avatars inside the group. An avatar that sets a size of its own keeps it.
`compact`	`boolean`	`false`
Applies the reduced density to every avatar inside. Unlike the size it is cumulative: an avatar cannot opt back out of a compact group.
`ringColor`	`string`	none
The colour of the ring drawn around each disc. It defaults to the page background, which is what makes the ring read as a gap between two avatars.
`label`	`string`	none
The accessible name of the group, such as "Project members": a row of faces does not say on its own who these people are. An `aria-label` or `aria-labelledby` of yours wins over it.

Slots

Slot	Type
`default`	`{}`
The VAvatars to stack.
`overflow`	`AvatarGroupOverflowSlotProps`
Replaces the "+X" disc standing for the avatars beyond `max`. It receives `count`, the number being hidden.

Types

The types the tables above name, written as the library declares them. The ones carrying export can be imported from vectis-ui to type your own code; the others are the shape of what a slot hands out.

export interface AvatarGroupOverflowSlotProps {
  count: number
}