ProfilePictureGroup (React)

React wrapper for displaying a group of profile pictures with overlap, tooltips, and dropdown

The ProfilePictureGroup React component is a type-safe wrapper around the <profile-picture-group> web component. It provides camelCase props, object prop handling, and event callbacks.

For the Web Component (HTML) documentation with kebab-case attributes, see ProfilePictureGroup.

Import

import { ProfilePicture, ProfilePictureGroup } from '@grasco/profile-picture';
// or
import { ProfilePicture, ProfilePictureGroup } from '@grasco/profile-picture/react';

Basic Usage

<ProfilePictureGroup max={4} size="lg"><ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" /><ProfilePicture extCustomerId="demo-user-1769430441537-fs5i098" alt="Marcus Webb" /><ProfilePicture extCustomerId="demo-user-1769431068241-t5mkiym" alt="Alice Spark" /></ProfilePictureGroup>

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.

Props

Prop	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)
`showAddButton`	`boolean`	`false`	Show add button
`addButtonLabel`	`string`	`'Add user'`	Add button a11y label
`animated`	`boolean`	`true`	Enable hover lift animation
`rotationAmount`	`number`	`0`	Alternating rotation degrees

Direction

<ProfilePictureGroup max={5} size="lg" direction="ltr"><ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" /></ProfilePictureGroup>

<ProfilePictureGroup max={5} size="lg" direction="rtl"><ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" /></ProfilePictureGroup>

Rotation

<ProfilePictureGroup max={5} size="lg" rotationAmount={8}><ProfilePicture extCustomerId="demo-user-1769431807927-pd9dtmn1" alt="Kerry Nicholson" /><ProfilePicture extCustomerId="demo-user-1769429613186-q8x65t0" alt="Sarah Chen" /><ProfilePicture extCustomerId="demo-user-1769430228786-ompo3g1" alt="Emma Liu" /><ProfilePicture extCustomerId="demo-user-1769430441537-fs5i098" alt="Marcus Webb" /></ProfilePictureGroup>

Pass a tooltip prop as a TooltipConfig object.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Enable tooltips
`position`	`'top' \| 'bottom' \| 'left' \| 'right'`	—	Position
`delay`	`number`	`300`	Delay before showing (ms)

Pass a dropdown prop as a DropdownConfig object.

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 and Events

<ProfilePictureGroupmax={3}size="lg"showAddButtontooltip={{ enabled: true, position: 'top' }}dropdown={{ showPresence: true }}onAvatarClick={(user) => console.log('Clicked:', user.name)}onAddClick={() => console.log('Add clicked')}>{users.map(u => (  <ProfilePicture    key={u.id}    extCustomerId={u.customerId}    alt={u.name}    data-user-id={u.id}    data-status={u.status}  />))}</ProfilePictureGroup>

React-Specific Props

Prop	Type	Description
`className`	`string`	CSS class name
`style`	`React.CSSProperties`	Inline styles
`children`	`React.ReactNode`	ProfilePicture children