Profile Picture UI
ProfilePictureGroup
Display a group of profile pictures with overlap, tooltips, and dropdown
The <profile-picture-group> web component arranges multiple <profile-picture> components into a compact, overlapping stack. It automatically handles overflow with a counter badge and provides built-in tooltip and dropdown support for hidden users.
This page documents the Web Component (HTML) usage. For the React wrapper, see React ProfilePictureGroup.
Basic Usage
<profile-picture-group max="4" size="lg"><profile-picture ext-customer-id="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson"></profile-picture><profile-picture ext-customer-id="demo-user-1769429613186-q8x65t0" alt="Sarah Chen"></profile-picture><profile-picture ext-customer-id="demo-user-1769430228786-ompo3g1" alt="Emma Liu"></profile-picture><profile-picture ext-customer-id="demo-user-1769430441537-fs5i098" alt="Marcus Webb"></profile-picture><profile-picture ext-customer-id="demo-user-1769431068241-t5mkiym" alt="Alice Spark"></profile-picture></profile-picture-group>When there are more children than the max value allows, the group displays a counter badge (e.g. "+2") representing the hidden users. Clicking the counter opens a dropdown listing those users.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
max | number | 4 | Max visible avatars before counter |
direction | 'ltr' | 'rtl' | 'ltr' | Stack direction |
overlap | number | 0.3 | Overlap percentage (0-1) |
size | Size | number | 'md' | Size inherited by children |
spacing | number | — | Spacing in px (overrides overlap) |
show-add-button | boolean | false | Show add button |
add-button-label | string | 'Add user' | Add button a11y label |
animated | boolean | true | Enable hover lift animation |
rotation-amount | number | 0 | Alternating rotation degrees |
Direction
<!-- Left to right (default) --><profile-picture-group max="5" size="lg" direction="ltr"><profile-picture ext-customer-id="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson"></profile-picture><profile-picture ext-customer-id="demo-user-1769429613186-q8x65t0" alt="Sarah Chen"></profile-picture><profile-picture ext-customer-id="demo-user-1769430228786-ompo3g1" alt="Emma Liu"></profile-picture></profile-picture-group><!-- Right to left --><profile-picture-group max="5" size="lg" direction="rtl"><profile-picture ext-customer-id="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson"></profile-picture><profile-picture ext-customer-id="demo-user-1769429613186-q8x65t0" alt="Sarah Chen"></profile-picture><profile-picture ext-customer-id="demo-user-1769430228786-ompo3g1" alt="Emma Liu"></profile-picture></profile-picture-group>Rotation
<profile-picture-group max="5" size="lg" rotation-amount="8"><profile-picture ext-customer-id="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson"></profile-picture><profile-picture ext-customer-id="demo-user-1769429613186-q8x65t0" alt="Sarah Chen"></profile-picture><profile-picture ext-customer-id="demo-user-1769430228786-ompo3g1" alt="Emma Liu"></profile-picture><profile-picture ext-customer-id="demo-user-1769430441537-fs5i098" alt="Marcus Webb"></profile-picture></profile-picture-group>Tooltip Config
Pass a tooltip attribute as a JSON string to configure tooltip behavior on each avatar.
| Property | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable tooltips |
position | 'top' | 'bottom' | 'left' | 'right' | — | Position |
delay | number | 300 | Delay before showing (ms) |
Dropdown Config
Pass a dropdown attribute as a JSON string to configure the overflow dropdown.
| Property | Type | Default | Description |
|---|---|---|---|
maxHeight | number | 280 | Max dropdown height |
showPresence | boolean | true | Show presence dots |
position | 'bottom' | 'top' | 'bottom' | Dropdown position |
With Add Button, Tooltip, and Dropdown
<profile-picture-groupmax="3"size="lg"show-add-buttontooltip='{"enabled": true, "position": "top"}'dropdown='{"showPresence": true}'><profile-picture ext-customer-id="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" data-user-id="demo-user-1769431807927-pd9dtmn1" data-status="online"></profile-picture><profile-picture ext-customer-id="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" data-user-id="demo-user-1769429613186-q8x65t0" data-status="away"></profile-picture><profile-picture ext-customer-id="demo-user-1769430228786-ompo3g1" alt="Emma Liu" data-user-id="demo-user-1769430228786-ompo3g1" data-status="busy"></profile-picture><profile-picture ext-customer-id="demo-user-1769430441537-fs5i098" alt="Marcus Webb" data-user-id="demo-user-1769430441537-fs5i098" data-status="offline"></profile-picture><profile-picture ext-customer-id="demo-user-1769431068241-t5mkiym" alt="Alice Spark" data-user-id="demo-user-1769431068241-t5mkiym" data-status="online"></profile-picture></profile-picture-group>