AvatarGroup
Stacked group of Avatar components with overflow counter, expand-on-hover and expand-on-click behaviours.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
Emplacements de contenu exposés par ce composant.
- #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
Événements émis par ce composant.
- @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
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <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.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- 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
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | 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.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- dimension0px
- Density offset applied to overlap margin calculation.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic group
Expand on hover
Vertical direction
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.