All components
Data Display
Avatar
stable
Since 1.2
Person or entity representation with image, initials, and placeholder states, six sizes, presence, verified, and custom badge overlays.
Data Display
primitive
Display
Documented
import { Avatar } from '@ivim/native/components';
When to use
Use when
Identifying a person or organization beside their name or content.
Showing presence or a verified status alongside that identity.
Don't use when
The image is the content itself rather than an identity — use a plain Image.
You need a stack of overlapping avatars — use AvatarGroup.
Playground
Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
AL
size
size
xs
sm
md
lg
xl
2xl
status
status
none
online
offline
busy
Verified
verified
Name
name
<Avatar name="Ada Lovelace" />
Example
Preview
Code
Content states
Initials
AL
Placeholder (no name)
?
Named (informative)
AL
Sizes
xs through 2xl
AL
AL
AL
AL
AL
AL
Overlays
Presence
AL
GH
KJ
Verified
AL
Custom badge
AL
9
Composition
With a name and email
AL
Ada Lovelace
ada@ivim.health
Overlapping group
AL
GH
KJ
+1
Anatomy
The parts that compose this component.
1
Container
Circular surface carrying the fill and hairline border.
2
Image or initials
The photo, falling back to initials, then to a placeholder.
3
Overlay
Presence dot, verified check, or a custom badge in the corner.
Guidelines
Do
Leave the avatar unnamed when the person’s name is already visible beside it — a named decorative avatar just repeats itself.
Do
Pass aria-label when the avatar is the only thing identifying the person, such as in a bare stack.
Do
Always pass name, even with an image, so initials are ready if the image fails.
Don't
Use presence color alone to convey status — pair it with text where the status matters.
Props
Public props for this component. Required props are marked; defaults reflect the component implementation.
name
string
Used to derive initials. Pass it even with an image.
source
ImageSourcePropType
Photo. Falls back to initials if loading fails.
aria-label
string
Makes the avatar an informative image. Omit when the name is already visible nearby.
size
'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | number
default: 'md'
Diameter, or an explicit pixel size.
status
'online' | 'offline' | 'busy'
Presence dot in the corner.
verified
boolean
default: false
Verified check overlay, taking precedence over status.
badge
ReactNode
Custom corner overlay — a company mark, a count. Replaces status and verified.
Deviations from Untitled UI
Where this component deliberately differs from Untitled UI's API, and why. These are kept choices, not gaps to close.
Untitled UI
`initials?: string` precomputed
Ours
`name?: string`, initials derived
Callers have names, not initials; deriving centralizes locale-aware initial logic. `status` adds `'busy'`; `source` is RN `ImageSourcePropType`.
Accessibility
Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
Unnamed by default: an avatar beside an already-labelled row is decorative, and naming it would announce the person twice.
•
Passing aria-label makes it an image with that name, for cases where the avatar is the only identity.
•
A failed image falls back to initials rather than leaving an empty disc.
•
The verified overlay carries its own "Verified" name so the status is not colour-only.
—
Not focusable. Wrap in a Pressable when the avatar itself is an action.
Platform & RTL
Behavior that differs across the platforms this component runs on.
Web
Image loading failure is detected via onError, the same path as native.
iOS
Initials render in the themed text scale for the size.
Android
Matches iOS.
RTL
The overlay corner mirrors with the writing direction.
State coverage
Interaction and visual states this component supports.
base
semantic color
density
Token references
Semantic design tokens this component page exercises. Tap one to edit it live.
Related components
Components that solve adjacent problems or compose with this one.
AvatarGroup
Overlapping stack of avatars with a "+N" overflow chip past a maximum.
Badge
Compact status or metadata label with six semantic tones plus seven non-semantic accent tones, four treatments, a pill or square shape, three sizes, dots, counts, adornments, and optional press and remove actions.
FeaturedIcon
Tonal container that frames an icon, in light, dark, outline, and modern treatments across four sizes and two shapes.
TagGroup
A row of tags: static labels, or single/multiple selection, with per-tag and group removal, dots, counts, and avatar slots.