Avatar API
API reference for the Avatar component: its props with their token values and defaults, the styled-system prop groups, and forwarded HTML attributes.
Demos
For usage examples, visit the component demo page: Avatar
Import
import { Avatar } from '@soroush.tech/design-system/Avatar'Avatar-specific props
src
Primary image URL.
<Avatar src="https://example.com/photo.jpg" alt="Jane Doe" />
srcSet
Forwarded to the inner <img> element's srcset attribute. Also used as the primary image source when src is absent.
alt
Alt text for the image. Required for accessibility when an image is rendered.
fallback
Secondary image URL shown when src (and srcSet) are absent or fail to load. children are shown only when both the primary source and fallback have failed.
<Avatar src={userPhoto} fallback="/default-avatar.svg" alt="Jane">
JD
</Avatar>
children
Rendered when no image source is available or all sources have errored - typically initials or an icon.
<Avatar bg="secondary">JD</Avatar>
variant
Controls the shape of the avatar container via border-radius.
| Value | border-radius |
|---|---|
"circular" | 50% |
"rounded" | theme.radii.md (8px) |
"square" | 0 |
Default: "circular".
size
Preset size - resolves against theme.avatar.
| Value | width / height |
|---|---|
"sm" | 32px |
"md" | 40px |
"lg" | 48px |
"xl" | 56px |
Default: "md".
ring
boolean - adds a CSS outline around the avatar.
Default: 1px solid theme.border.primary with outline-offset: 2px.
ringColor
Overrides the ring color - resolves against theme.border.
| Token | Description |
|---|---|
"light" | Subtle border |
"primary" | Accent color (default) |
"dark" | High-contrast border |
ringWidth
Overrides the ring width - resolves against theme.borderWidths.
| Token | Value |
|---|---|
"none" | 0 |
"thin" | 1px (default) |
"base" | 2px |
"thick" | 4px |
Styled-system props
Avatar extends Flex minus all padding props. Outer spacing (m, mt, mr, mb, ml, mx, my) adjusts margin via theme.space. Padding is intentionally excluded - the image fills the container with object-fit: cover and padding would break the fill.
Source code
If this page does not answer your question, have a look at the implementation of the component for more detail.