Client component

Avatar

User images with graceful fallbacks, status badges, and overlapping groups.

"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>
  );
}

name

size

shape

colorScheme

ring

import { Avatar } from "astralis-ui";

<Avatar />

Import#

import { Avatar } from "astralis-ui";
// Avatar.Group, Avatar.Badge

Usage#

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#

"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#

"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`	None	The image, with its alt text.
`name`	`string`	None	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 15 schemes`	`from name`	Explicit hue override.
`ring`	`boolean`	`false`	Border ring (automatic inside a Group).

Avatar.Group#

Prop	Type	Default	Description
`max`	`number`	None	How many avatars to show; the rest collapse into a +N chip.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	`"md"`	Applied to every avatar in the group.
`spacing`	`number`	`-8`	Overlap between avatars, in pixels. Negative values overlap.

Avatar.Badge#

Prop	Type	Default	Description
`status`	`"online" \| "away" \| "busy" \| "offline"`	`"online"`	Preset dot color.
`color`	`string`	None	Custom dot color, overriding status.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"`	None	Dot size. Taken from the avatar it sits in.