Avatar

Installation

$ npx shadcn@latest add https://goodui.dev/r/avatar.json

The file lands in components/goodui/avatar.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/avatar works too.

Usage

import { Avatar, AvatarGroup } from "@/components/goodui/avatar"

const team = [
  { name: "Maya Chen", src: "/team/maya.jpg" },
  { name: "Leo Park", src: "/team/leo.jpg" },
  { name: "Ana Ruiz" },
  { name: "Sam Okafor" },
  { name: "Priya Nair" },
  { name: "Tom Becker" },
]

export function StylistRow() {
  return (
    <div className="flex items-center justify-between rounded-lg border p-4">
      <div className="flex items-center gap-3">
        <Avatar name="Maya Chen" src="/team/maya.jpg" size="lg" status="online" />
        <div className="text-sm">
          <p className="font-medium">Maya Chen</p>
          <p className="text-muted-foreground">Senior stylist · 6 bookings today</p>
        </div>
      </div>
      <AvatarGroup size="sm" max={4} tooltips>
        {team.map((p) => (
          <Avatar key={p.name} name={p.name} src={p.src} />
        ))}
      </AvatarGroup>
    </div>
  )
}

When to use

Examples

<Avatar name="Glow Studio" src="/brand/glow.png" size="xl" ring="story" animation="spin" />

<AvatarGroup max={3} onMoreClick={() => setShowAttendees(true)}>
  {attendees.map((a) => <Avatar key={a.id} name={a.name} src={a.avatarUrl} />)}
</AvatarGroup>

<Avatar name="Ana Ruiz" shape="squircle" ring="solid" tone="success" />

API reference

Accessibility

• •With an image, the <img> gets alt from alt or name. Without one, the avatar is role="img" with aria-label from alt or name, and the initials are aria-hidden.
• •The status dot carries visually hidden text ("online", "away"…), translatable with labels.
• •The "+N" chip has an aria-label ("5 more", or "Show 5 more" when it is a button); translate both with AvatarGroup labels.
• •Group tooltips are CSS-only and appear on hover, not on focus. Do not put information there that is not also available elsewhere.

Motion

• •The image fades in over 350 ms once loaded; an image already in cache shows immediately.
• •spin rotates a gradient or story ring every 3 s. pulse makes the ring breathe (scale 1.07, every 2 s), or sends a halo outward when there is no ring. pop-in scales from 0.4 with overshoot in 500 ms on mount.
• •statusPulse pings the status dot to 2.4× every 1.6 s.
• •AvatarGroup: hovering the group fans the avatars apart in 300 ms and the hovered one rises 3px; tooltips fade in over 150 ms.
• •Reduced motion: every animation and transition is off, the halo and status ping are hidden and the group does not fan out.

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

FAQ

Related