Avatar

A photo when the account has one, falling back to one or two initials on an identity disc: the name resolves to one of ten hues, and the disc is that hue's diagonal blend from a pale tint to a deeper, warmer neighbour, so one person keeps one colour on every platform and stays distinct in a stack or list. The initials are bold, about a third of the disc, in near-black, which holds 4.5:1 on both ends of every blend.
Like a photo, the disc is identity content: it keeps its colours under glass, where only the neutral tile of an avatar with no name or initials takes the control material. AvatarMenu builds the signed-in account control on the same circle: one capsule trigger carrying the avatar, the name, and the email, opening the account menu under that same identity.
AO
iOS
AO
Android
AO
Web
tsx
<Avatar name="AO" />

Props

AvatarMenu

Prop
Description
name
string
The account holder's full name: the pill's first line, the avatar's initials fallback and colour identity, and the menu header's title.
email
string
The secondary line under the name in the pill, and the menu header's description (typically the account's email address).
src
string
The account photo. Falls back to the initials exactly like `Avatar`.
initials
string
Ready-made initials for the avatar, used verbatim when there is no photo.
items
required
DropdownItem[]
The menu rows, top to bottom. Same rows as `Dropdown` (icon, shortcut, destructive, disabled, separatorBefore).
compact
boolean
Avatar and chevron only, no name block: the topbar form of the pill.
alignStart
boolean
Hang the menu from the pill's LEADING edge instead of its trailing one.
alignEnd
boolean
The default, spelled out: the menu's trailing edge meets the pill's.
disabled
boolean
Dimmed, non-opening pill: the menu never opens and the press is inert.
open
boolean
Controlled open state. Omit for uncontrolled (the pill opens/closes it).
onOpenChange
(open: boolean) => void
Fired when the open state changes (pill press, row select, dismissal).
onSelect
(item: DropdownItem, index: number) => void
Fired with the selected row and its index when a menu row is pressed.
testID
string
E2E hook forwarded to the root element.
style
LayoutStyle
Outer layout composition only (placement within a parent), never a restyle hook.

Avatar

Prop
Description
src
string | number
The photo. A remote/URI string, or a bundled image module from `require(...)` / `import`. When set (and it loads), the image fills the circle and the initials fallback is hidden; if the image fails to load, it falls back to the initials.
uri
string | number
Alias for `src`, for callers that think in terms of a native image uri.
name
string
Full name. Drives the initials fallback AND the accessible label/alt text.
initials
string
Ready-made initials, used verbatim as the glyph (overrides `name`/`children`).
children
ReactNode
Same as `name`; the rendered initials when no photo is supplied.
accessibilityLabel
string
Accessible name for the avatar (the photo's alt text and, when pressable, the button's label). Falls back to `name`, then string `children`. Set it for a photo-only or pressable avatar that has no `name`.
tiny
boolean
Size (pick one; default is the 40px row avatar, `tiny` the 24px disc a capsule holds). Precedence: `tiny` > `small` > `large`.
small
boolean
Size (pick one; default is the 40px row avatar, `tiny` the 24px disc a capsule holds). Precedence: `tiny` > `small` > `large`.
large
boolean
Size (pick one; default is the 40px row avatar, `tiny` the 24px disc a capsule holds). Precedence: `tiny` > `small` > `large`.
circle
boolean
Shape (pick one; default is a circle).
rounded
boolean
Shape (pick one; default is a circle).
ring
boolean
Separator outline, for avatars that overlap in a stack.
onPress
() => void
When set, the avatar becomes pressable (e.g. a topbar account trigger).
testID
string
E2E hook forwarded to the root element.
style
LayoutStyle
For layout composition only; overlap/stacking is owned by AvatarGroup, not this prop.

AvatarGroup

Prop
Description
children
ReactNode
Avatar elements to stack.
max
number
Cap the visible avatars; the remainder collapses into a "+N" chip.
total
number
Override the total behind the "+N" chip (e.g. a server-known member count).
tiny
boolean
Size (pick one; forwarded to every child so the whole stack is uniform). Precedence: `tiny` > `small` > `large`.
small
boolean
Size (pick one; forwarded to every child so the whole stack is uniform). Precedence: `tiny` > `small` > `large`.
large
boolean
Size (pick one; forwarded to every child so the whole stack is uniform). Precedence: `tiny` > `small` > `large`.
tight
boolean
Overlap tightness (pick one; default `tight`). Precedence loose > snug > tight.
snug
boolean
Overlap tightness (pick one; default `tight`). Precedence loose > snug > tight.
loose
boolean
Overlap tightness (pick one; default `tight`). Precedence loose > snug > tight.
accessibilityLabel
string
Accessible name for the whole group (e.g. "8 members").
testID
string
E2E hook forwarded to the root element.

Do & Don’t

Single

Don’t
ABCD
Cramming in a full set of initials shrinks the type and crowds the circle.
Do
AO
One or two initials, about a third of the disc.

Stacked

Don’t
AO
RC
LB
KT
JD
MA
AL
SK
An unbounded stack (no max) runs off the row and stops being scannable.
Do
AO
RC
LB
KT
+12
Cap the stack with max and let AvatarGroup summarize the rest as a +N count.

Topbar account menu

Don’t
A bare avatar with no Dropdown around it is decorative, not a trigger, and opens nothing.
Do
Press the avatar: AvatarMenu compact makes it a real trigger in a bar with no room for a name, and the account is named in the menu header the moment the menu opens.

Identity

Don’t
Rachel Chen
rachel.chen@example.com
Equal weight on the name and email flattens the hierarchy.
Do
Rachel Chen
rachel.chen@example.com
Name primary; email muted and secondary.

Menu header

Don’t
Ada Lovelace
admin@example.com
Squaring the avatar here clashes with the circular avatars everywhere else.
Do
Ada Lovelace
admin@example.com
Keep one consistent circular avatar shape across contexts.

Account identity

Don’t
Hand-composing the identity beside the trigger drifts from the pill's type and spacing, and the menu that opens names no account at all.
Do
Press the pill: name and email go through AvatarMenu, which owns both lines, the shared press target, and the identity header on the menu it opens.

Sign out

Don’t
Sign out buried mid-list, in the same tone as its neighbours, is one slip away on the path to Settings.
Do
Open the menu: keep the destructive sign out last and behind a separator, a reach away from the rows people press every day.

Compact trigger

Don’t
compact on a roomy page that names the account nowhere else hides who is signed in behind a press, to save room the row never needed.
Do
Press the pill: where the row has space, the full form says who is signed in before anything is opened.

Unavailable account

Don’t
Disabling every row instead leaves the pill live: it still opens, onto a menu where nothing can be pressed.
Do
disabled on the pill itself: the whole trigger dims, the press is inert, and the button announces itself disabled instead of inviting a press that goes nowhere.
← Autocomplete
Badge →