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: tappable.
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. |
onPress | () => void | — | Makes the avatar pressable, for example to open a profile. |
style | StyleProp<ViewStyle> | — | Extra styles for the container. |
Avatar.Group
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Avatar elements. They overlap and get a ring in the background color. |
max | number | — | Number of avatars shown before a +N counter. |
size | AvatarSize | 'sm' | Applied to every avatar in the group. |
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 max shows participants without taking a whole row per person.
<Avatar.Group max={3}>
{attendees.map((a) => (
<Avatar key={a.id} source={{ uri: a.photo }} name={a.name} />
))}
</Avatar.Group>