AvatarGroup
Stacked group of Avatar components with overflow counter, expand-on-hover and expand-on-click behaviours.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-avatar-group> — 3 parts: root wrapper, item avatars and overflow rest chip.- 1.origam-avatar-group
- Root element. Renders as an inline-flex container with
role="group". Direction modifier class controls flex-direction. - 2.origam-avatar-group__item
- Each visible avatar. Receives a negative margin-inline-start (horizontal) or margin-block-start (vertical) to create the overlap stack effect.
- 3.origam-avatar-group__rest
- Overflow avatar showing the +N count. Visible only when items.length > max. Same overlap margin as __item.
API
Props
All props accepted by this component, with their type, default value and description.
- itemsArray<IAvatarProps>[]
- Array of avatar data objects. Each entry is forwarded as props to an inner OrigamAvatar.
- maxnumber5
- Maximum number of avatars to show before collapsing into a +N overflow chip.
- expandOnHoverbooleanfalse
- When true, hovering the group expands all hidden avatars by setting margin to 0.
- expandOnClickbooleanfalse
- When true, clicking the group toggles the expanded state. Collapses when clicking outside.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Stacking direction. horizontal stacks left-to-right; vertical stacks top-to-bottom.
- density
- Density forwarded to every child avatar.
- Border-radius forwarded to every child avatar.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- size
- Size applied to every child avatar via OrigamDefaultsProvider.
- tagstring'div'
- HTML element rendered as the group root.
- color
- Foreground color forwarded to every child avatar.
- bgColor
- Background color forwarded to every child avatar.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- elevationTElevation
- Box-shadow elevation forwarded to every child avatar.
- hoverboolean | IStateEffectConfig
- hoverClassstring
- activeboolean | IStateEffectConfig
- activeClassstring
API
Slots
Content slots exposed by this component.
- #avatar
- Override the rendering of each visible avatar. Receives the item data and its index.
- #rest
- Override the +N overflow chip. Receives the hidden items array and its length.
- #default
- Content inside the overflow chip avatar (the +N label). Replaces the default count text.
API
Emits
Events emitted by this component.
- @update:activeany
- @hoverboolean
- Fired when the hover state changes. Propagated from the group interaction.
- @update:hoverboolean
- @activeboolean
- Fired when the active/click state changes (expand-on-click groups).
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child component.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed group styles.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- CSS position of the group root.
- Flex direction. Overridden by direction modifier classes.
- Density offset. compact: -6px, comfortable: 10px. Applied to overlap margin calculation.
- Horizontal overlap margin for each avatar item (horizontal mode).
- Transition duration for the margin animation on expand.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Moves focus through each interactive avatar within the group. |
| Enter / Space | Activates expand-on-click behaviour when expandOnClick=true. |
Notes
- The root element has role="group" to semantically group related avatars for screen readers.
- When expandOnClick=true, clicking outside the group (v-click-outside) collapses it automatically.
- Transition on the overlap margin respects prefers-reduced-motion via the transition-property var.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- dimension0px
- Density offset applied to overlap margin calculation.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic group
Expand on hover
Vertical direction
Ecosystem
Family
Components from the same folder that share conventions and often compose together.