# 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`](/chat/docs/sdk/react-native/ui-components/base-ui/user-avatar/) and [`ChannelAvatar`](/chat/docs/sdk/react-native/ui-components/base-ui/channel-avatar/) are built on top of this component.

When an `imageUrl` is provided, the component renders an image using `ImageComponent` from [`useComponentsContext()`](/chat/docs/sdk/react-native/customization/custom_components/). If the image fails to load or no URL is supplied, the `placeholder` node is rendered instead.

## Usage

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

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

With a custom placeholder:

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

## Props

| Prop              | Description                                                                                                                                                                                             | Type                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `size` (required) | The size of the avatar. Controls both the width and height of the circular container. Accepted values: `'2xl'` (64x64), `'xl'` (48x48), `'lg'` (40x40), `'md'` (32x32), `'sm'` (24x24), `'xs'` (20x20). | `'2xl'` \| `'xl'` \| `'lg'` \| `'md'` \| `'sm'` \| `'xs'` |
| `imageUrl`        | URL of the image to display. If the image fails to load, the component falls back to rendering the `placeholder`.                                                                                       | `string`                                                  |
| `placeholder`     | Custom React node rendered when `imageUrl` is not provided or fails to load. Typically used for initials or a fallback icon.                                                                            | `ReactNode`                                               |
| `showBorder`      | Whether to show a subtle border around the avatar. Defaults to `undefined`.                                                                                                                             | `boolean`                                                 |
| `backgroundColor` | Background color of the avatar container. Defaults to `semantics.avatarPaletteBg1` from the theme.                                                                                                      | `ColorValue`                                              |
| `style`           | Additional style applied to the outer container.                                                                                                                                                        | `StyleProp<ViewStyle>`                                    |


---

This page was last updated at 2026-04-17T17:33:46.402Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/ui-components/base-ui/avatar/](https://getstream.io/chat/docs/sdk/react-native/ui-components/base-ui/avatar/).