Avatar

The Avatar component is used to represent a user, displaying an image, initials, or an icon. Avatars can be grouped using the AvatarGroup component.

Installation

$ cbui-cli install @crossbuildui/avatar

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Avatar, AvatarGroup, AvatarIcon } from '@/crossbuildui/avatar';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // If using custom icons

The default fallback icon AvatarIcon uses react-native-vector-icons/MaterialIcons. Ensure this library is installed and linked in your Expo project if you rely on the default icon or plan to use custom icons from this library.

Avatar Component

Basic Usage

Provide an image src and/or a name for initials.

index.tsx

<Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026024d" name="Jane Doe" />
<Avatar name="John Smith" /> {/* Will show initials JS */}

Fallbacks

Avatars can display initials, a custom icon, or a completely custom fallback component if the image source is unavailable or fails to load. The showFallback prop (default true) controls this behavior.

index.tsx

// Initials (default if no src or src fails, and name is provided)
<Avatar name="Sarah Connor" color="primary" />

// Custom Icon
<Avatar icon={<Icon name="account-circle" size={24} color="white" />} color="secondary" />

// Custom Fallback Component (overrides icon and initials)
const CustomFallback = () => (
  <View style={{width: '100%', height: '100%', backgroundColor: 'lightcoral', justifyContent: 'center', alignItems: 'center'}}>
    <Text style={{color: 'white', fontWeight: 'bold'}}>Error</Text>
  </View>
);
<Avatar src="https://invalid-url.xyz/image.png" fallback={<CustomFallback />} />

// No fallback shown
<Avatar src="https://invalid-url.xyz/image.png" name="No Fallback" showFallback={false} />

Sizes

Avatars come in sm, md (default), and lg sizes.

index.tsx

<Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026704d" size="sm" />
<Avatar src="https://i.pravatar.cc/150?u=a04258114e29026702d" size="md" />
<Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026024d" size="lg" />

Radius

Control the border radius with none, sm, md, lg, or full (default).

index.tsx

<Avatar name="NR" radius="none" color="success" />
<Avatar name="SM" radius="sm" color="warning" />
<Avatar name="MD" radius="md" color="danger" />
<Avatar name="LG" radius="lg" color="primary" />
<Avatar name="FL" radius="full" color="secondary" /> {/* Default */} 

Colors

The color prop affects the background of fallbacks (initials/icon) and the border color if isBordered is true.

index.tsx

<Avatar name="DF" color="default" />
<Avatar name="PR" color="primary" />
<Avatar name="SE" color="secondary" />
<Avatar name="SU" color="success" />
<Avatar name="WA" color="warning" />
<Avatar name="DA" color="danger" />

Bordered & Disabled

Use isBordered to add a border and isDisabled for a disabled appearance.

index.tsx

// Bordered
<Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026704d" isBordered color="primary" />

// Disabled
<Avatar src="https://i.pravatar.cc/150?u=a04258114e29026702d" isDisabled />
<Avatar name="Disabled" isDisabled isBordered color="secondary" />

Custom Image Component

Use the ImgComponent prop to render the avatar image with a custom component, e.g., for image caching libraries like react-native-fast-image. Pass additional props to this custom component via imgProps.

index.tsx

import FastImage from 'react-native-fast-image';

<Avatar
  src="https://my-cdn.com/user-image.jpg"
  name="Cached User"
  ImgComponent={FastImage}
  imgProps={{
    priority: FastImage.priority.high,
    resizeMode: FastImage.resizeMode.contain,
  }}
/>

AvatarGroup Component

Basic Usage

Group multiple Avatar components. They will overlap by default. Props like size, color, radius, isBordered, and isDisabled can be set on AvatarGroup to apply to all children, unless overridden by an individual Avatar.

index.tsx

<AvatarGroup>
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026024d" name="User 1" />
  <Avatar src="https://i.pravatar.cc/150?u=a04258114e29026702d" name="User 2" />
  <Avatar name="U3" color="primary" />
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026704d" name="User 4" />
</AvatarGroup>

Max & Total Count

Use max to limit the number of visible avatars. Excess avatars are represented by a count. The total prop can override the count derived from children length.

index.tsx

<AvatarGroup max={3} total={10}>
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026024d" />
  <Avatar src="https://i.pravatar.cc/150?u=a04258114e29026702d" />
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026704d" />
  {/* These won't be rendered, count will be +7 */}
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026706d" />
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026707d" />
</AvatarGroup>

<AvatarGroup max={2} color="secondary" size="lg">
  <Avatar name="A" />
  <Avatar name="B" />
  <Avatar name="C" />
  <Avatar name="D" />
</AvatarGroup> {/* Shows A, B, and +2 count */} 

Custom Count Renderer

Provide a custom component for the count indicator using the renderCount prop.

index.tsx

const renderCustomCount = (count) => (
  <View style={{
    width: 32, height: 32, borderRadius: 16, backgroundColor: 'purple',
    justifyContent: 'center', alignItems: 'center', marginLeft: -10, zIndex: 999,
    borderWidth: 2, borderColor: 'white'
  }}>
    <Text style={{color: 'white', fontSize: 12}}>{count} more</Text>
  </View>
);

<AvatarGroup max={2} renderCount={renderCustomCount}>
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026024d" />
  <Avatar src="https://i.pravatar.cc/150?u=a04258114e29026702d" />
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026704d" />
  <Avatar src="https://i.pravatar.cc/150?u=a042581f4e29026706d" />
</AvatarGroup>

Props Overview

Avatar Props

PROP	TYPE	DESCRIPTION
`src`	`ImageSourcePropType \| string`	Image source URI or local asset.
`name`	`string`	User's name for initials fallback.
`icon`	`ReactElement<AvatarIconProps>`	Custom icon for fallback.
`fallback`	`ReactElement`	Custom component for fallback (overrides icon/initials).
`color`	`AvatarColor`	Semantic color for fallback/border. Default: `'default'`.
`size`	`AvatarSize`	Size of the avatar. Default: `'md'`.
`radius`	`AvatarRadius`	Border radius. Default: `'full'`.
`isBordered`	`boolean`	Show border. Default: `false` (true in group).
`isDisabled`	`boolean`	Disabled appearance. Default: `false`.
`showFallback`	`boolean`	Show fallback if src fails. Default: `true`.
`imgProps`	`Omit<ImageProps, 'source' \| 'style'>`	Props for the underlying Image component.
`ImgComponent`	`ComponentType<ImageProps>`	Custom Image component.
`styles`	`AvatarSlotsStyles`	Custom styles for avatar slots (base, img, fallback, initials, icon).
`style`	`StyleProp<ViewStyle>`	Style for the avatar's outer container.
`onError`	`ImageProps['onError']`	Callback on image load error.

AvatarGroup Props

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactElement<AvatarProps> \| ReactElement<AvatarProps>[]`	-	Avatar components.
`max`	`number`	5	Max visible avatars.
`total`	`number`	-	Total avatars for count display.
`size`	`AvatarSize`	`'md'`	Default size for avatars in group.
`color`	`AvatarColor`	`'default'`	Default color for avatars.
`radius`	`AvatarRadius`	`'full'`	Default radius for avatars.
`isBordered`	`boolean`	`true`	Default border state for avatars.
`isDisabled`	`boolean`	`false`	Default disabled state for avatars.
`isGrid`	`boolean`	`false`	Grid layout (affects overlap).
`renderCount`	`(count: number) => ReactElement`	-	Custom renderer for the count indicator.
`style`	`StyleProp<ViewStyle>`	-	Style for the group container.
`countStyles`	`base?: ViewStyle; text?: TextStyle`	-	Styles for the count indicator.

AvatarIcon Props

The AvatarIcon is a simple component used as the default fallback icon. It primarily accepts size, color, and style. It renders a MaterialIcons "person" icon by default.

PROP	TYPE	DEFAULT	DESCRIPTION
`size`	`number`	24	Icon size.
`color`	`string`	`'#FFFFFF'`	Icon color.
`style`	`StyleProp<ViewStyle>`	-	Style for the icon container.
`path`	`string`	-	Path for SVG icons (if adapted).

Styling

Avatar Styling

Customize the Avatar appearance using:

style prop on Avatar for its outermost container.
styles prop on Avatar to provide styles for internal slots:
- base: The main container View.
- img: The Image component itself.
- fallback: The container for fallback content (initials/icon).
- initials: The Text component for initials.
- icon: The container View for the icon within fallback.

index.tsx

<Avatar
  src="https://i.pravatar.cc/150?u=a042581f4e29026024d"
  name="Styled Avatar"
  size="lg"
  isBordered
  color="primary"
  style={{ margin: 10, transform: [{ rotate: '5deg' }] }} // Styles the outer View container
  styles={{
    base: { shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.25, shadowRadius: 3.84, elevation: 5 },
    img: { opacity: 0.8 },
    // fallback: { backgroundColor: 'darkslateblue' },
    // initials: { color: 'white', fontStyle: 'italic' },
    // icon: { padding: 4 }
  }}
/>

AvatarGroup Styling

Customize the AvatarGroup appearance using:

style prop on AvatarGroup for its main container.
countStyles prop on AvatarGroup to style the count indicator:
- base: The container View for the count.
- text: The Text component for the count number.

index.tsx

<AvatarGroup
  max={3}
  style={{ paddingVertical: 10, backgroundColor: '#eee', borderRadius: 20 }}
  countStyles={{
    base: { backgroundColor: 'teal', borderColor: 'white' },
    text: { color: 'white', fontWeight: 'normal' }
  }}
>
  <Avatar name="S1" color="success" />
  <Avatar name="S2" color="success" />
  <Avatar name="S3" color="success" />
  <Avatar name="S4" color="success" />
</AvatarGroup>

Accessibility

The Avatar components include accessibility features:

Avatar:
- The image has an accessibilityLabel derived from the name prop or a default "User avatar".
- If interactive (e.g., wrapped in a Pressable by the user), ensure appropriate roles and states are added.
AvatarGroup:
- The group container can be given an accessibilityLabel (e.g., "Group of users").
- The count indicator has an implicit label (e.g., "+5"). Consider adding a more descriptive label if renderCount is used.

Accordion Badge

Avatar

Installation

Import

Avatar Component

Basic Usage

Fallbacks

Sizes

Radius

Colors

Bordered & Disabled

Custom Image Component

AvatarGroup Component

Basic Usage

Max & Total Count

Custom Count Renderer

Props Overview

Avatar Props

AvatarGroup Props

AvatarIcon Props

Styling

Avatar Styling

AvatarGroup Styling

Accessibility

Avatar Group

Fallbacks

Radius Variants

Colors Variants