[Avatar] Fix AvatarGroup sizing, wire up disabled prop, and forward Base UI props
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 70
- Forks
- 13
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 8
Description
Summary
Improvements to the Avatar component to fix bugs, forward missing Base UI props, and improve AvatarGroup reliability.
API Differences from Base UI
| Base UI | Apsara | Change |
|---|---|---|
Avatar.Root |
Avatar |
Flattened — root is the default |
Avatar.Image |
(none) | Hidden inside Avatar, exposed via src/alt props |
Avatar.Fallback |
(none) | Hidden inside Avatar, exposed via fallback prop |
| (none) | AvatarGroup |
Custom addition |
| (none) | getAvatarColor |
Custom utility |
Props not forwarded from Base UI
- Image:
onLoadingStatusChange— callback for tracking image load/error state - Fallback:
delay— delay before showing fallback (avoids flash for fast-loading images)
Improvements
1. Fix AvatarGroup overlap CSS (size selectors don't match)
The CSS defines .avatar-size-N .avatarWrapper selectors, but AvatarGroup renders a plain <div> — the size classes are on individual avatars inside .avatarWrapper, not on a parent, so the overlap selectors never match.
2. Wire up disabled prop to CVA
The CVA config has disabled: { true: styles['avatar-disabled'] } but AvatarProps doesn't include disabled as a prop — it's never passed to the CVA call.
3. Forward onLoadingStatusChange from Image
Base UI's Avatar.Image supports onLoadingStatusChange for tracking image load/error state. Currently not exposed.
4. Forward delay from Fallback
Base UI supports a delay prop on Avatar.Fallback to avoid a flash when the image loads quickly. Currently not exposed.
5. Improve getAvatarProps robustness
The recursive prop extraction only works if the direct child is an Avatar or has a single children prop. Wrapping in Tooltip or other components with different prop structures may fail silently.
6. Fix array index key in AvatarGroup
avatars.map((avatar, index) => <div key={index}> — if the avatar list changes order, React won't reconcile correctly.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start from the Avatar and AvatarGroup implementations, including their CVA configuration and recursive getAvatarProps logic. Trace how Base UI image and fallback props are exposed, then verify that sizing, disabled styling, prop forwarding, robust child extraction, and stable avatar reconciliation all behave as described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- design, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100