raystack / raystack/apsara

[Avatar] Fix AvatarGroup sizing, wire up disabled prop, and forward Base UI props

Open
#597 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

component triage
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.