Skip to content

feat: Add fallbackClassName prop to AvatarGroupItem#6

Merged
robdimarco-atxp merged 2 commits intomainfrom
fix/avatar-group-class-separation
Jan 26, 2026
Merged

feat: Add fallbackClassName prop to AvatarGroupItem#6
robdimarco-atxp merged 2 commits intomainfrom
fix/avatar-group-class-separation

Conversation

@robdimarco-atxp
Copy link
Contributor

Problem

AvatarGroupItem was passing the same className to both the Avatar container and AvatarFallback, causing class conflicts:

  • Background colors intended for the fallback (e.g., bg-indigo-500) were also being applied to the container
  • Border classes intended for the container (e.g., border-2 border-surface-primary) were also being applied to the fallback
  • This made it unclear which element would get which styles
  • Even with tailwind-merge, the mixing of concerns was confusing

Solution

Add a separate fallbackClassName prop specifically for AvatarFallback styling:

  • className → Avatar container (border, sizing, positioning)
  • fallbackClassName → AvatarFallback (background, text color)

The default bg-muted text-foreground remains in AvatarFallback, so it won't be blank when no fallbackClassName is provided.

Benefits

  1. Clear separation of concerns - Container styling vs fallback styling are explicit
  2. No class conflicts - Each element gets only its relevant classes
  3. Better API - Usage intent is clear and documented
  4. Backward compatible - Existing usage with className still works

Example Usage

// Before (ambiguous - same classes on both elements)
<AvatarGroupItem 
  fallback="JD"
  className="bg-indigo-500 text-white border-2 border-surface-primary"
/>

// After (explicit - clear separation)
<AvatarGroupItem 
  fallback="JD"
  className="border-2 border-surface-primary"
  fallbackClassName="bg-indigo-500 text-white"
/>

Breaking Change

No - This is additive. Existing usage with className still works, but components that were relying on className to style the fallback should migrate to fallbackClassName for clarity.

Test Plan

  • ✅ Built package successfully
  • ✅ Updated LibreChat to use fallbackClassName
  • Verify avatar colors now render correctly with no conflicts
  • Check other components in design system using AvatarGroupItem

Add separate fallbackClassName prop for better control over avatar colors.

Problem: AvatarGroupItem was passing the same className to both Avatar
container and AvatarFallback, causing class conflicts. Background colors
intended for the fallback were also being applied to the container, and
vice versa (border classes on fallback).

Solution: Add fallbackClassName prop specifically for AvatarFallback styling.
- className → Avatar container (border, sizing)
- fallbackClassName → AvatarFallback (background, text color)
- Default bg-muted text-foreground remains for when no fallbackClassName provided

Benefits:
- Clear separation of concerns (container vs fallback styling)
- No class conflicts between container and fallback
- Explicit API makes usage intent clear
- Fallback won't be blank when no custom color provided

Breaking change: No - existing usage with className still works, just passes
to container only. Components relying on className for fallback colors should
migrate to fallbackClassName.
Add two new stories demonstrating fallbackClassName prop usage:
- CustomColors: Shows vivid colors with white text contrast
- CustomBordersAndColors: Shows separating container (borders) from fallback (colors)

Also update all existing stories to use fallbackClassName instead of className
for background colors, following the new API pattern.
@robdimarco-atxp robdimarco-atxp merged commit 3713958 into main Jan 26, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant