Avatar
User images with graceful fallbacks, status badges, and overlapping groups.
NS
AK
ML
SP
"use client";
import { Avatar, HStack } from "astralis-ui";
export function AvatarDemo() {
return (
<HStack gap="3">
{/* Initials with a hue derived deterministically from the name. */}
<Avatar name="Nova Starling" />
<Avatar name="Alex Kim" />
<Avatar name="Maria Lopez" />
{/* No name, no image → icon fallback. */}
<Avatar />
<Avatar name="Sam Patel">
<Avatar.Badge status="online" />
</Avatar>
</HStack>
);
}Import#
import { Avatar } from "astralis-ui";
// Avatar.Group, Avatar.BadgeUsage#
The fallback chain is automatic: src image → initials from name (with a
hue derived deterministically from the name, so the same person always gets
the same color) → silhouette icon. Avatar.Badge anchors a status dot.
Groups#
NS
AK
ML
+2
"use client";
import { Avatar } from "astralis-ui";
export function AvatarGroup() {
return (
/* Overlapping stack; everything past `max` collapses into "+N". */
<Avatar.Group max={3}>
<Avatar name="Nova Starling" />
<Avatar name="Alex Kim" />
<Avatar name="Maria Lopez" />
<Avatar name="Sam Patel" />
<Avatar name="Jo Ellis" />
</Avatar.Group>
);
}Sizes and shapes#
NS
NS
NS
NS
NS
NS
NS
NS
"use client";
import { Avatar, HStack } from "astralis-ui";
const sizes = ["xs", "sm", "md", "lg", "xl", "2xl"] as const;
export function AvatarSizes() {
return (
<HStack gap="4" alignItems="end" wrap="wrap" justifyContent="center">
{sizes.map((size) => (
<Avatar key={size} name="Nova Starling" size={size} />
))}
<Avatar name="Nova Starling" shape="rounded" />
<Avatar name="Nova Starling" shape="square" />
</HStack>
);
}Props#
| Prop | Type | Default | Description |
|---|---|---|---|
src / alt | string | — | The image, with its alt text. |
name | string | — | Drives initials and the deterministic hue. |
icon | ReactNode | silhouette | Custom fallback when no image or name. |
size | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "md" | Diameter. |
shape | "circle" | "rounded" | "square" | "circle" | Outline shape. |
colorScheme | all 11 schemes | from name | Explicit hue override. |
ring | boolean | false | Border ring (automatic inside a Group). |
Avatar.Group#
| Prop | Type | Default | Description |
|---|---|---|---|
max | number | — | Visible cap; the rest collapse into a "+N" chip. |
spacing | number | -8 | Overlap in pixels. |
size | Avatar sizes | "md" | Applied to every child. |
Avatar.Badge#
| Prop | Type | Default | Description |
|---|---|---|---|
status | "online" | "away" | "busy" | "offline" | "online" | Preset dot colors. |
color | string | — | Custom color, overriding status. |