Data Display · astro-ui · Avatar
Avatar
User image with initials fallback, status badges, rings, groups, and loading state.
Avatar renders an when src is provided, otherwise initials derived from name. Beyond the base surface it composes the extras design systems need: an online status badge (four states, four corners), colored rings, radius overrides, custom explicit sizes, a grayscale filter (with hover-to-restore), a loading spinner veil, and a badge slot for counts or checkmarks. AvatarGroup stacks avatars with overlap and an optional trailing count chip (numeric or icon) with an optional hover-spread.
Features
- Status badges: online/away/busy/offline on any corner, with accessible labels
- Rings in five token colors plus the background key line
- Radius overrides (none/sm/md/lg/full) on top of circle/square/rounded shapes
- Custom explicit sizes (px or rem) alongside the 7-step size scale
- Grayscale filter with optional hover-to-restore
- Loading state with spinner veil over the media
- Badge slot for counts, checkmarks, or icon badges
- AvatarGroup: overlap stack, numeric/icon count chip, hover spread
Usage
---
import { Avatar, AvatarGroup } from "astro-ui";
---
<Avatar name="Ada Lovelace" src="/ada.jpg" />
<Avatar name="Grace" status="online" />
<Avatar name="Alan" ring="primary" size="lg" />
<AvatarGroup hover>
<Avatar name="Ada" /><Avatar name="Grace" />
<Fragment slot="count">+3</Fragment>
</AvatarGroup>Demos
Basic
<Avatar name="Ada Lovelace" />
<Avatar name="Grace Hopper" />Shapes & variants
<Avatar name="Grace Hopper" />
<Avatar name="Grace Hopper" shape="rounded" />
<Avatar name="Grace Hopper" shape="square" />
<Avatar name="Alan Turing" variant="primary" />
<Avatar name="Alan Turing" variant="muted" />Image
<Avatar src="https://placehold.co/64x64/1f2937/9ca3af?text=ada" alt="Ada Lovelace" />
<Avatar src="https://placehold.co/64x64/1f2937/9ca3af?text=hopper" alt="Grace Hopper" fit="contain" />Different border radiuses
<Avatar radius="sm" name="Ada L" />
<Avatar radius="md" name="Ada L" />
<Avatar radius="lg" name="Ada L" />
<Avatar radius="full" name="Ada L" />Different sizes
<Avatar size="xs" name="A L" />
<Avatar size="sm" name="A L" />
<Avatar size="md" name="A L" />
<Avatar size="lg" name="A L" />
<Avatar size="xl" name="A L" />
<Avatar size="2xl" name="A L" />Custom sizes
<Avatar customSize={16} name="A L" />
<Avatar customSize={32} name="A L" />
<Avatar customSize={56} name="A L" />
<Avatar customSize="4.5rem" name="A L" />Online status
<Avatar name="Ada L" status="online" />
<Avatar name="Grace H" status="away" />
<Avatar name="Alan T" status="busy" />
<Avatar name="Edsger D" status="offline" />Status badge positions
<Avatar name="Ada L" status="online" statusPosition="top-left" />
<Avatar name="Grace H" status="online" statusPosition="top-right" />
<Avatar name="Alan T" status="online" statusPosition="bottom-left" />
<Avatar name="Edsger D" status="online" statusPosition="bottom-right" />Avatar with badge icon
+1
<Avatar name="Ada L">
<Badge slot="badge" variant="primary" size="sm">+1</Badge>
</Avatar>Solid background fallback
<Avatar name="Ada L" variant="primary" />
<Avatar name="Grace H" variant="success" />
<Avatar name="Alan T" variant="warning" />
<Avatar name="Edsger D" variant="info" />Basic avatar group
<AvatarGroup>
<Avatar name="Ada L" /><Avatar name="Grace H" /><Avatar name="Alan T" />
</AvatarGroup>Avatar group with icon count
<AvatarGroup>
<Avatar name="Ada L" /><Avatar name="Grace H" /><Avatar name="Alan T" />
<Fragment slot="count">
<span aria-hidden="true">+</span>
</Fragment>
</AvatarGroup>Avatar group with numerical count
+5
<AvatarGroup>
<Avatar name="Ada L" /><Avatar name="Grace H" /><Avatar name="Alan T" />
<Fragment slot="count">+5</Fragment>
</AvatarGroup>Avatar group with online status
<AvatarGroup>
<Avatar name="Ada L" status="online" />
<Avatar name="Grace H" /><Avatar name="Alan T" />
</AvatarGroup>Grayscale image filter
<Avatar name="Ada L" filter="grayscale" filterHover />Avatar group with hover effect
<AvatarGroup hover>
<Avatar name="Ada L" /><Avatar name="Grace H" /><Avatar name="Alan T" /><Avatar name="Edsger D" />
</AvatarGroup>Custom verification badge
<Avatar name="Ada L">
<Badge slot="badge" variant="success" size="sm" ariaLabel="Verified">
<svg aria-hidden="true" width="12" height="12" viewBox="0 0 12 12" fill="none">
<path d="m2.5 6.5 2.25 2.25L9.5 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />
</svg>
</Badge>
</Avatar>Avatar with multiple badges
3
<Avatar name="Ada L" status="online" statusPosition="bottom-right">
<span class="avatar-count-badge" slot="badge" aria-label="3 notifications">3</span>
</Avatar>Gradient animated ring
<Avatar name="Ada L" class="avatar-gradient-ring" />
<style>
/* conic-gradient ring behind the avatar */
</style>Animated ring
<Avatar name="Ada L" class="avatar-story-ring" />
<style>
/* rotating gradient ring */
</style>Loading state
The spinner scales with the avatar (em-based) — with a 10px floor on xs.
<Avatar name="Ada L" size="sm" loading />
<Avatar name="Ada L" size="xl" loading />
<!-- The spinner scales with the avatar; override with --aui-avatar-spinner -->
<Avatar name="Ada L" size="3xl" loading style="--aui-avatar-spinner: 2rem" />Compact social proof with initials
<div style="display:grid;justify-items:start;gap:var(--ui-space-2)">
<div style="display:flex;align-items:center">
<Avatar name="Ada Lovelace" size="xs" status="online" />
<Avatar name="Grace Hopper" size="xs" />
<Avatar name="Alan Turing" size="xs" />
<Avatar name="Edsger Dijkstra" size="xs" variant="primary" />
<Avatar name="Barbara Liskov" size="xs" />
</div>
<p style="margin:0;color:var(--ui-muted-foreground);font-size:var(--ui-text-xs)">Trusted by engineers at</p>
<p style="margin:0;color:var(--ui-foreground);font-size:var(--ui-text-sm);font-weight:var(--ui-font-medium)">Ada Lovelace, Grace Hopper, Alan Turing, and 247 more</p>
</div>Avatar group with hover tooltips and lift effect
+1
<AvatarGroup hover>
<Tooltip ariaLabel="Ada Lovelace" placement="top">
<Fragment slot="content">Ada Lovelace</Fragment>
<Avatar name="Ada Lovelace" />
</Tooltip>
<Tooltip ariaLabel="Grace Hopper" placement="top">
<Fragment slot="content">Grace Hopper</Fragment>
<Avatar name="Grace Hopper" />
</Tooltip>
<Tooltip ariaLabel="Alan Turing" placement="top">
<Fragment slot="content">Alan Turing</Fragment>
<Avatar name="Alan Turing" />
</Tooltip>
<Tooltip ariaLabel="Edsger Dijkstra" placement="top">
<Fragment slot="content">Edsger Dijkstra</Fragment>
<Avatar name="Edsger Dijkstra" />
</Tooltip>
<Fragment slot="count">+2</Fragment>
</AvatarGroup>Avatar social proof with text label
<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--ui-space-4)">
<AvatarGroup>
<Avatar name="Ada Lovelace" status="online" />
<Avatar name="Grace Hopper" />
<Avatar name="Alan Turing" />
<Avatar name="Edsger Dijkstra" />
<Avatar name="Barbara Liskov" />
</AvatarGroup>
<div style="display:grid;gap:var(--ui-space-1)">
<p style="margin:0;color:var(--ui-foreground);font-size:var(--ui-text-sm);font-weight:var(--ui-font-semibold)">Joined by 2,411 developers this week</p>
<p style="margin:0;color:var(--ui-muted-foreground);font-size:var(--ui-text-xs)">See why teams choose this stack for production Astro sites.</p>
</div>
</div>Pill small outline button with avatar
<Button variant="outline" size="sm" shape="rounded">
<Avatar name="Ada Lovelace" size="xs" />
<span style="margin-inline-start:var(--ui-space-2)">Ada</span>
</Button>
<Button variant="outline" size="sm" shape="rounded">
<Avatar name="Grace Hopper" size="xs" />
<span style="margin-inline-start:var(--ui-space-2)">Grace</span>
</Button>
<Button variant="outline" size="sm" shape="rounded">
<Avatar name="Alan Turing" size="xs" status="online" />
<span style="margin-inline-start:var(--ui-space-2)">Alan</span>
</Button>Avatar group with hover effect and tooltips
+3
<AvatarGroup hover>
<Tooltip ariaLabel="Ada Lovelace" placement="bottom" variant="light">
<Fragment slot="content">Ada Lovelace</Fragment>
<Avatar name="Ada Lovelace" status="online" />
</Tooltip>
<Tooltip ariaLabel="Grace Hopper" placement="bottom" variant="light">
<Fragment slot="content">Grace Hopper</Fragment>
<Avatar name="Grace Hopper" />
</Tooltip>
<Tooltip ariaLabel="Alan Turing" placement="bottom" variant="light">
<Fragment slot="content">Alan Turing</Fragment>
<Avatar name="Alan Turing" ring="success" />
</Tooltip>
<Tooltip ariaLabel="Edsger Dijkstra" placement="bottom" variant="light">
<Fragment slot="content">Edsger Dijkstra</Fragment>
<Avatar name="Edsger Dijkstra" />
</Tooltip>
<Tooltip ariaLabel="Barbara Liskov" placement="bottom" variant="light">
<Fragment slot="content">Barbara Liskov</Fragment>
<Avatar name="Barbara Liskov" ring="primary" />
</Tooltip>
<Fragment slot="count">+3</Fragment>
</AvatarGroup>Avatar inside an empty state
No team members yet
Invite your first teammate to start collaborating on projects, deploys, and analytics.
<Empty size="lg" ariaLabel="No team members yet">
<Avatar slot="media" name="Your team" size="xl" variant="primary" ring="primary" />
<Fragment slot="title">No team members yet</Fragment>
<Fragment slot="description">Invite your first teammate to start collaborating on projects, deploys, and analytics.</Fragment>
<Fragment slot="footer">
<Button size="sm">Invite member</Button>
<Button size="sm" variant="ghost" href="/docs/get-started/">Read the guide</Button>
</Fragment>
</Empty>API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | — | Image URL; astro:assets optimization when resolvable. |
name | string | — | Full name — drives the accessible name and initials fallback. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "md" | Seven-step size scale. |
customSize | string | number | — | Explicit box size (px number or CSS length) overriding size. |
radius | "none" | "sm" | "md" | "lg" | "full" | — | Corner override on top of shape. |
status | "online" | "away" | "busy" | "offline" | — | Presence dot rendered on a corner. |
statusPosition | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "bottom-right" | Corner carrying the status dot. |
badgePosition | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-right" | Corner anchoring slotted badges to the avatar's border. |
statusLabel | string | per status | Accessible label for the status indicator. |
ring | "primary" | "success" | "warning" | "destructive" | "info" | "background" | — | Colored ring with background key line. |
filter | "none" | "grayscale" | "none" | Image filter treatment. |
filterHover | boolean | false | Restores color on hover when filter=grayscale. |
loading | boolean | false | Spinner veil over the media. |
variant | 8 token colors | "inherit" | Fallback background scheme (solid color fallbacks). |
class | string | — | Merged via cn(); Tailwind classes welcome. |
id | string | — | Element id. |
Accessibility
Implemented accessibility features — semantics, ARIA wiring, and keyboard behavior that ship with the component.
- Root carries role=img with an accessible name (aria-label or resolved alt)
- Status dot is role=status with a spoken label (Online, Away, Do not disturb, Offline)
- Loading veil is aria-hidden decoration; the avatar keeps its name throughout
- Group is role=group with a default User group label; the count chip keeps its text content
FAQ
How do I add a notification count?
Use the badge slot: <Avatar><Badge slot="badge" variant="destructive">3</Badge></Avatar>. Combine with status for two independent indicators.
How does the gradient/animated ring work?
The ring demos compose a wrapper with a conic-gradient background behind the avatar (see each demo's code tab). The ring prop covers static rings; animated story rings stay in user CSS.
Changelog
Version history mentioning Avatar.
v0.1.0 — 2026-11-11
added
- Data display (10): Badge, Avatar, Attachment, Table, Progress, Bubble, Chart, Empty, Tag, Timeline.