Components

Avatar

A user's photo, initials, or fallback character built on Radix Avatar: automatic image loading state with fallback during load and on error. Supports sm/md/lg sizes plus an optional status dot for online/away/offline presence.

Installation

terminal

npx shadcn@latest add @wuko/avatar

Sizes

Three sizes: sm (28px), md (40px), lg (56px). Pick by container density: sm for table rows, md for inline mentions, lg for profile headers.

VKVKVK

components/profile-row.tsx

import { Avatar } from "@/components/ui/avatar";

export function ProfileRow() {
  return (
    <div className="flex items-center gap-4">
      <Avatar fallback="VK" size="sm" />
      <Avatar fallback="VK" size="md" />
      <Avatar
        src="/brand/wuko.png"
        alt="Wuko Kitsune"
        fallback="VK"
        size="lg"
      />
    </div>
  );
}

With status

Pass status to render a presence dot at the bottom-right corner. Three states: online (green), away (amber), offline (muted). The dot includes an aria-label so screen readers announce the status alongside the avatar.

VAO

components/presence-list.tsx

import { Avatar } from "@/components/ui/avatar";

export function PresenceList() {
  return (
    <div className="flex items-center gap-4">
      <Avatar fallback="V" status="online" />
      <Avatar fallback="A" status="away" />
      <Avatar fallback="O" status="offline" />
    </div>
  );
}

Props

Prop	Type	Default	Description
src	string	—	Image URL. When the image successfully loads, it's shown; until then (or on load error), the fallback renders.
alt	string	—	Image alt text. Required for accessibility when src is provided.
fallback	string	"?"	Initials or short text shown when no src is provided, while the image loads, or after a load error. Defaults to "?" when omitted.
size	"sm" \| "md" \| "lg"	"md"	Avatar diameter. Three sizes: sm (28px), md (40px), lg (56px). Status dot scales proportionally.
status	"online" \| "away" \| "offline"	—	Optional presence indicator rendered as a colored dot at the bottom-right corner. Includes aria-label so screen readers announce the status.
className	string	—	Tailwind classes merged onto the Avatar.Root span (the outermost element).
...rest	ComponentPropsWithoutRef<typeof Avatar.Root>	—	Forwarded to the underlying Radix Avatar.Root: id, aria-, data-, onClick, etc. Excludes children (constructed internally) and size (redefined as a string union).

← Previous

Alert

Badge