Skip to content

OrigamAvatarGroup ​

<OrigamAvatarGroup> displays a cluster of OrigamAvatar chips with controlled overlap and an automatic "+N" rest counter. The cluster can expand on hover or click so users can browse the full member list without leaving the surface.

Basic usage ​

Pass an array of avatar prop objects through items. Anything beyond max (default 5) is collapsed into a single overflow avatar that displays +N.

vue
<template>
    <OrigamAvatarGroup
        :items="[
            { text: 'AP' },
            { text: 'JC' },
            { text: 'MS' },
            { text: 'KL' },
            { text: 'RT' },
            { text: 'NB' },
            { text: 'OT' }
        ]"
    />
</template>

Direction ​

direction accepts 'horizontal' (default) or 'vertical'. Both flavours reuse the same overlap math — only the axis differs.

vue
<template>
    <OrigamAvatarGroup direction="horizontal" :items="people" />
    <OrigamAvatarGroup direction="vertical"   :items="people" />
</template>

Max ​

max controls how many avatars are shown before the overflow chip kicks in. Setting max to a value greater than or equal to the items length renders every avatar without an overflow chip.

vue
<template>
    <OrigamAvatarGroup :items="people" :max="3" />
</template>

Expand on hover / click ​

Either toggles the max cap to the full length when triggered. They are mutually compatible — wire both if you want a click-to-pin behaviour after a hover preview.

vue
<template>
    <OrigamAvatarGroup :items="people" expand-on-hover />
    <OrigamAvatarGroup :items="people" expand-on-click />
</template>

Density ​

density retunes the overlap between consecutive avatars. The base overlap is a flat -18px (margin-inline-start on horizontal, margin-block-start on vertical, applied to every child but the first); density contributes an offset to that value through --origam-avatar-group---density:

density--origam-avatar-group---densityResulting marginEffect
compact-6pxcalc(-18px + -6px) = -24pxtightens the cluster by 6px per avatar
default0pxcalc(-18px + 0px) = -18pxthe baseline overlap
comfortable10pxcalc(-18px + 10px) = -8pxloosens the cluster by 10px per avatar

⛔ An earlier version of this page claimed "compact / comfortable both shave 8 pixels". Neither figure was right, and comfortable does not shave anything — it is the one rung that spreads the avatars apart.

expandOnHover / expandOnClick override the whole calculation while engaged: the margin drops to 0, whatever the density.

vue
<template>
    <OrigamAvatarGroup :items="people" density="compact" />
    <OrigamAvatarGroup :items="people" density="comfortable" />
</template>

Forwarded avatar props ​

Any avatar-level prop set directly on the group is propagated to every member through mergeProps. This is the recommended way to keep the cluster visually consistent (same size, rounded, border).

vue
<template>
    <OrigamAvatarGroup
        :items="people"
        size="small"
        rounded
        border
    />
</template>

Slots ​

SlotSlot propsDescription
avatar{ item, index }Override the rendering of a single member.
rest{ rest, length }Override the overflow chip.
default—Override the overflow chip content (label) only.

Events ​

EventPayloadDescription
update:activebooleanActive toggled by click.
update:hoverbooleanHover toggled on mouse enter / leave.

Props (interface) ​

ts
interface IAvatarGroupProps extends ICommonsComponentProps,
    IDirectionProps, IDensityProps, IRoundedProps, ISizeProps,
    ITagProps, IColorProps, IPaddingProps, IMarginProps, IBorderProps,
    IElevationProps, IHoverProps, IActiveProps {
    items?: Array<IAvatarProps>
    max?: number
    expandOnHover?: boolean
    expandOnClick?: boolean
}

Anatomy ​

html
<div class="origam-avatar-group origam-avatar-group--horizontal
            origam-avatar-group--expand-on-hover">
    <div class="origam-avatar origam-avatar-group__item">…</div>
    <div class="origam-avatar origam-avatar-group__item">…</div>
    <div class="origam-avatar origam-avatar-group__rest">+3</div>
</div>

Design tokens consumed ​

CSS variablePurpose
--origam-avatar-group---flex-directionrow / column driven by direction.
--origam-avatar-group---densityDensity shaving propagated to children.
--origam-avatar-group__avatar---transitionTransition used on hover / active expansion.
--origam-avatar-group---margin-inline-startNegative margin between siblings (horizontal).
--origam-avatar-group---margin-block-startNegative margin between siblings (vertical).
--origam-avatar-group__item---outline-colorSeparation-ring color on every stacked __item / __rest chip. Default: color.surface.default.
--origam-avatar-group__item---outline-widthSeparation-ring width. Default: 2px.
--origam-avatar-group__item---outline-styleSeparation-ring style. Default: solid.

The full list lives in packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/) — grep for --origam-avatar-group---.

Accessibility ​

  • The wrapper carries role="group" so screen readers announce a cohesive entity instead of disjoint avatars.
  • When expandOnHover is on, also wire expandOnClick so keyboard users can reach the full list — pure-hover affordances are not reachable from the keyboard. With expandOnClick, the wrapper is focusable (tabindex="0") and exposes aria-expanded; Enter/Space toggle the same expansion a pointer click does.
  • The overflow chip is purely visual; if its content matters (e.g. the literal count), wrap the cluster in an aria-label="N collaborators" container.

Theming notes ​

  • Theme switching propagates through every member automatically — the cluster does not cache anything.
  • Visual-token props (border, rounded, elevation, color, bgColor, density, size, borderColor, borderStyle) set on <origam-avatar-group> are forwarded to every child <origam-avatar> as defaults — a prop the group never received falls through to whatever an ancestor <OrigamDefaultsProvider> or the active theme's components['origam-avatar'] block defines (e.g. a brand theme's border: true), instead of silently overriding it. Only a prop the CONSUMER actually set on the group wins over the theme (issue #263).
  • The group-level override applied at the group root is the box-shadow when elevated.
  • Separation ring: every stacked child (__item and the __rest overflow chip) gets a structural outline — a distinct CSS property from each avatar's own box-shadow/border, so the two never collide or need to be layered — that keeps overlapping avatars legible against whatever surface the group sits on. It is themable via the dedicated --origam-avatar-group__item---outline-* cssVars above and defaults to color.surface.default; only avatars rendered inside an <origam-avatar-group> get it — a standalone <origam-avatar> never does.
  • OrigamAvatar — single chip; the group is just an arranger.
  • OrigamChip — labelled, removable counterpart.