This is beta documentation for Stream Chat React Native SDK v9. For the latest stable version, see the latest version (v8) .

Avatar

Avatar is the lowest-level avatar primitive in the SDK. It renders a circular image container with an optional placeholder fallback and border. Higher-level components like UserAvatar and ChannelAvatar are built on top of this component.

When an imageUrl is provided, the component renders an image using the ImageComponent from ChatContext. If the image fails to load or no URL is supplied, the placeholder node is rendered instead.

Usage

import { Avatar } from "stream-chat-react-native";

<Avatar size="xl" imageUrl="https://example.com/avatar.png" showBorder />;

With a custom placeholder:

<Avatar
  size="lg"
  placeholder={<CustomPlaceholderIcon />}
  backgroundColor="#E8F0FE"
/>

Props

`size` (required)

The size of the avatar. Controls both the width and height of the circular container.

Type	Values
string	`'2xl'` \| `'xl'` \| `'lg'` \| `'md'` \| `'sm'` \| `'xs'`

Size mapping:

Size	Dimensions
`2xl`	64 × 64
`xl`	48 × 48
`lg`	40 × 40
`md`	32 × 32
`sm`	24 × 24
`xs`	20 × 20

`imageUrl`

URL of the image to display. If the image fails to load, the component falls back to rendering the placeholder.

Type
string

`placeholder`

Custom React node rendered when imageUrl is not provided or fails to load. Typically used for initials or a fallback icon.

Type
ReactNode

`showBorder`

Whether to show a subtle border around the avatar.

Type	Default
boolean	`undefined`

`backgroundColor`

Background color of the avatar container. Defaults to semantics.avatarPaletteBg1 from the theme.

Type
ColorValue

`style`

Additional style applied to the outer container.

Type
`StyleProp<ViewStyle>`

Overview

UserAvatar