Avatar
Avatar represents a person or entity with an image or a stable, name-derived fallback. When an image is missing or fails to load, Avatar displays the first meaningful character of the name on a deterministic pastel gradient.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | Required | Identity used for the label, initial and gradient |
| src | string | - | Optional image URL |
| size | "small" | "medium" | "large" | "medium" | Avatar size |
| badge | ReactNode | - | Element positioned at the bottom-right |
| jss | JSS | - | Exceptional root styles |
Generated identity
The pastel palette is selected from the normalized name rather than generated randomly at render time. The same identity therefore keeps the same restrained treatment across sessions, themes and server rendering.
<Avatar name="Gerard Moreno" />
<Avatar name="Ada Lovelace" />
Image fallback
Avatar displays the generated identity while an image is unavailable and returns to it automatically if the image fails to load.
<Avatar name={user.name} src={user.avatarUrl} />
Sizes
<Avatar name="Gerard Moreno" size="small" />
<Avatar name="Gerard Moreno" size="medium" />
<Avatar name="Gerard Moreno" size="large" />
Badges
Avatar owns badge placement on the circular edge while the existing Badge component owns its visual meaning. Badge placement is intentionally fixed rather than configurable.
<Avatar
name={user.name}
src={user.avatarUrl}
badge={<Badge size="small" color="highlight" />}
/>
Do not rely on badge color alone to communicate status. Include the status in adjacent text or in the accessible label of the surrounding control.
Stacks
Use AvatarStack for overlapping groups rather than applying negative margins to individual avatars. The default overlap works across Avatar sizes and can be adjusted for denser compositions.
<AvatarStack>
<Avatar name="Maya Chen" />
<Avatar name="Noah Williams" />
<Avatar name="Iris Okafor" />
</AvatarStack>
Composition
Avatar is visual rather than interactive. Wrap it in BaseButton or BaseLink to provide the appropriate semantics without adding interaction variants to Avatar itself.
<BaseButton
bare
color="secondary"
aria-label="Open Gerard's account"
onClick={openAccount}
jss={{ padding: 0, borderRadius: "50%" }}
>
<Avatar name="Gerard Moreno" src={avatarUrl} />
</BaseButton>
The same BaseButton can be rendered by PopoverTrigger when the avatar opens a menu. PopoverTrigger continues to own expanded state and overlay behavior.