Avatar
Profile image with an initials fallback.
Installation
npx axiom add avatarpnpm dlx axiom add avataryarn dlx axiom add avatarbun x axiom add avatarAlso copies: text.
Colors come from avatar.default.default.{background,foreground,ring} and avatar.status.default.{online,away,busy,offline} in the component tokens. colorFromName picks step 500 of a palette hue.
Usage
import { Avatar } from "@/components/ui/avatar";
<Avatar source={{ uri: user.photoUrl }} fallback="JC" />;Props
Avatar
| Prop | Type | Default | Description |
|---|---|---|---|
source | ImageSourcePropType | — | The image. While it loads, or if it fails, the fallback is shown. |
fallback | string | ReactNode | — | Shown without an image: usually 1–2 initials, or an icon. |
name | string | — | Full name. Used to compute initials when fallback is missing, and as the accessibility label. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | 'md' | sm, md and lg come from the avatar size tokens (32, 40, 56pt). xs is 24, xl is 88. A number sets it directly. |
shape | 'circle' | 'square' | 'circle' | square uses the md radius, for companies, groups or apps. |
status | 'online' | 'away' | 'busy' | 'offline' | — | Dot on the bottom-right corner, ringed with the background color. |
colorFromName | boolean | false | Picks a stable palette hue from name for the fallback background, so each person keeps the same color. |
style | StyleProp<ViewStyle> | — | Extra styles for the container. |
Avatar.Group
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Avatar and Avatar.Overflow elements. They overlap and get a ring in the background color. |
overlap | SpacingToken | 2 | How far each avatar slides under the previous one, from the spacing scale. |
The group shows every child you give it: it doesn’t cut the list or set sizes. Give each avatar its own size, slice the list yourself and end it with an Avatar.Overflow.
Avatar.Overflow
| Prop | Type | Default | Description |
|---|---|---|---|
count | number | — | People not shown, read as +count. |
size | AvatarSize | 'md' | Match the avatars next to it. |
Pressable
An avatar is a picture, not a button. To open a profile, wrap it in a Tappable:
<Tappable
accessibilityRole="button"
accessibilityLabel="Open Ada's profile"
onPress={openProfile}
>
<Avatar name="Ada Lovelace" source={{ uri: ada.photo }} />
</Tappable>Use cases
Chat header
A small avatar with a status next to the title tells who you’re talking to and whether they’re around.
<Avatar
size="sm"
source={{ uri: contact.photo }}
name={contact.name}
status={contact.online ? "online" : undefined}
/>Missing photo
Without an image, initials on a color derived from the name. The same person always gets the same color.
<Avatar
name={member.name}
source={member.photo ? { uri: member.photo } : undefined}
colorFromName
/>Who’s involved
Avatar.Group with an Avatar.Overflow shows participants without taking a whole row per person.
<Avatar.Group>
{attendees.slice(0, 3).map((a) => (
<Avatar key={a.id} source={{ uri: a.photo }} name={a.name} size="sm" />
))}
{attendees.length > 3 ? (
<Avatar.Overflow count={attendees.length - 3} size="sm" />
) : null}
</Avatar.Group>