{
  "schemaVersion": 1,
  "target": "react",
  "name": "avatar",
  "version": "0.1.0",
  "category": "data",
  "title": "Avatar",
  "description": "An avatar with an image, an initials fallback, five sizes, a presence dot, and an AvatarGroup that collapses extras into a count, built on Base UI Avatar.",
  "tags": [
    "avatar",
    "user",
    "presence",
    "group",
    "base-ui"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/avatar",
  "props": [
    {
      "name": "Avatar name",
      "type": "string",
      "description": "Person or agent name: the initials and the accessible name."
    },
    {
      "name": "Avatar src",
      "type": "string",
      "description": "Image URL. Initials show while it loads or if it fails."
    },
    {
      "name": "Avatar size",
      "type": "\"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\"",
      "default": "\"md\"",
      "description": "20, 24, 32, 40, or 56 pixels."
    },
    {
      "name": "Avatar status",
      "type": "\"online\" | \"away\" | \"busy\" | \"offline\" | \"working\"",
      "description": "Presence dot cut out by a ring in the page color. working marks an agent doing work."
    },
    {
      "name": "Avatar shape",
      "type": "\"circle\" | \"square\"",
      "default": "\"circle\"",
      "description": "Square suits organizations and workspaces."
    },
    {
      "name": "Avatar fallback",
      "type": "ReactNode",
      "description": "Replaces the initials, for example with an icon."
    },
    {
      "name": "Avatar fallbackDelay",
      "type": "number",
      "default": "300",
      "description": "Milliseconds before initials show while an image loads."
    },
    {
      "name": "AvatarGroup max / size / label",
      "type": "number / AvatarSize / string",
      "description": "Avatars to show before a +N count, the size for all, and the group's accessible name."
    }
  ],
  "accessibility": [
    "Each avatar is one image (role=\"img\") named after the person, including status (\"Jonas Weber, online\"); the inner image and initials are hidden from assistive technology.",
    "The overflow count is named \"2 more: Aiko Tanaka, Sam Ortiz\" and lists the names in its tooltip.",
    "Status reads in the accessible name, not by color alone.",
    "The photo fades in over 200ms when it loads; reduced motion shows it at once."
  ],
  "states": [
    "image",
    "initials",
    "icon fallback",
    "status",
    "group",
    "overflow"
  ],
  "files": [
    {
      "path": "ui/avatar.tsx",
      "content": "\"use client\";\n\nimport { Avatar as BaseAvatar } from \"@base-ui/react/avatar\";\nimport { Children, type ComponentProps, createContext, isValidElement, type ReactNode, useContext } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst sizes = {\n  xs: { box: \"size-5 text-[9px]\", dot: \"size-1.5 ring-[1.5px]\", overlap: \"[&>*+*]:-ms-0.5\" },\n  sm: { box: \"size-6 text-[10px]\", dot: \"size-2 ring-[1.5px]\", overlap: \"[&>*+*]:-ms-1\" },\n  md: { box: \"size-8 text-xs\", dot: \"size-2.5 ring-2\", overlap: \"[&>*+*]:-ms-1.5\" },\n  lg: { box: \"size-10 text-sm\", dot: \"size-3 ring-2\", overlap: \"[&>*+*]:-ms-2\" },\n  xl: { box: \"size-14 text-base\", dot: \"size-3.5 ring-[2.5px]\", overlap: \"[&>*+*]:-ms-3\" },\n} as const;\n\nexport type AvatarSize = keyof typeof sizes;\n\nconst statuses = {\n  online: { dot: \"bg-emerald-500\", label: \"Online\" },\n  away: { dot: \"bg-amber-500\", label: \"Away\" },\n  busy: { dot: \"bg-red-500\", label: \"Busy\" },\n  offline: { dot: \"bg-zinc-400 dark:bg-zinc-500\", label: \"Offline\" },\n  // For agents: the avatar is doing work right now.\n  working: { dot: \"bg-sky-500\", label: \"Working\" },\n} as const;\n\nexport type AvatarStatus = keyof typeof statuses;\n\nconst GroupContext = createContext<{ size: AvatarSize; grouped: boolean } | null>(null);\n\n/** First letter of the first and last word: \"Mara Okafor\" becomes \"MO\", \"deploy-bot\" becomes \"D\". */\nexport function getInitials(name: string) {\n  const words = name.trim().split(/\\s+/).filter(Boolean);\n  const first = words[0]?.[0] ?? \"\";\n  const last = words.length > 1 ? (words[words.length - 1]?.[0] ?? \"\") : \"\";\n  return (first + last).toUpperCase();\n}\n\nexport interface AvatarProps extends Omit<ComponentProps<\"span\">, \"children\"> {\n  /** Image URL. While it loads, or if it fails, the initials show instead. */\n  src?: string;\n  /** The person's or agent's name. Used for the initials and the accessible name. */\n  name: string;\n  size?: AvatarSize;\n  /** A presence dot at the bottom right, cut out of the avatar by a ring in the page color. */\n  status?: AvatarStatus;\n  /** Replaces the initials, for example with an icon for a bot or a team. */\n  fallback?: ReactNode;\n  /** Square corners suit organizations and workspaces; people stay round. */\n  shape?: \"circle\" | \"square\";\n  /** Milliseconds to wait before showing the fallback, so fast images do not flash initials first. */\n  fallbackDelay?: number;\n}\n\n/**\n * A profile picture with an initials fallback, built on Base UI Avatar. Announced as one image\n * named after the person, including their status when one is set.\n */\nexport function Avatar({\n  src,\n  name,\n  size: sizeProp,\n  status,\n  fallback,\n  shape = \"circle\",\n  fallbackDelay,\n  className,\n  ...props\n}: AvatarProps) {\n  const group = useContext(GroupContext);\n  const size = sizeProp ?? group?.size ?? \"md\";\n  const radius = shape === \"circle\" ? \"rounded-full\" : size === \"xs\" || size === \"sm\" ? \"rounded-[5px]\" : \"rounded-lg\";\n  const label = status ? `${name}, ${statuses[status].label.toLowerCase()}` : name;\n\n  return (\n    <span\n      role=\"img\"\n      aria-label={label}\n      data-slot=\"avatar\"\n      data-status={status}\n      className={cx(\"relative inline-flex shrink-0 align-middle\", className)}\n      {...props}\n    >\n      <BaseAvatar.Root\n        aria-hidden=\"true\"\n        className={cx(\n          \"relative inline-flex items-center justify-center overflow-hidden font-medium select-none\",\n          // A tint layered over the page color: reads as a soft fill, yet stays opaque where avatars overlap.\n          \"bg-white bg-linear-to-b from-zinc-950/[0.05] to-zinc-950/[0.05] text-zinc-600\",\n          \"dark:bg-black dark:from-white/[0.09] dark:to-white/[0.09] dark:text-zinc-300\",\n          // A hairline inside the edge keeps light photos from bleeding into a white page.\n          \"after:pointer-events-none after:absolute after:inset-0 after:rounded-[inherit] after:border after:border-zinc-950/10 dark:after:border-white/10\",\n          group?.grouped && \"ring-2 ring-white dark:ring-black\",\n          sizes[size].box,\n          radius,\n        )}\n      >\n        {src ? (\n          <BaseAvatar.Image\n            src={src}\n            alt=\"\"\n            className={cx(\n              \"size-full object-cover\",\n              \"transition-opacity duration-200 ease-out motion-reduce:transition-none data-[starting-style]:opacity-0\",\n            )}\n          />\n        ) : null}\n        <BaseAvatar.Fallback delay={src ? fallbackDelay ?? 300 : 0} className=\"leading-none [&_svg]:size-[55%]\">\n          {fallback ?? getInitials(name)}\n        </BaseAvatar.Fallback>\n      </BaseAvatar.Root>\n      {status ? (\n        <span\n          aria-hidden=\"true\"\n          className={cx(\n            \"absolute right-0 bottom-0 rounded-full ring-white dark:ring-black\",\n            shape === \"square\" && \"translate-x-1/4 translate-y-1/4\",\n            \"transition-[background-color] duration-200 ease-out motion-reduce:transition-none\",\n            statuses[status].dot,\n            sizes[size].dot,\n          )}\n        />\n      ) : null}\n    </span>\n  );\n}\n\nexport interface AvatarGroupProps extends ComponentProps<\"div\"> {\n  /** Size for every avatar in the group. */\n  size?: AvatarSize;\n  /** How many avatars to show before collapsing the rest into a `+N` count. */\n  max?: number;\n  /** Accessible name for the group, for example \"Reviewers\". */\n  label?: string;\n}\n\n/**\n * Overlapping avatars with an overflow count. Each avatar is ringed in the page color so the\n * overlap reads as a stack. The count lists the hidden names in its tooltip and accessible name.\n */\nexport function AvatarGroup({ size = \"md\", max, label, className, children, ...props }: AvatarGroupProps) {\n  const items = Children.toArray(children).filter(isValidElement);\n  const visible = max != null && items.length > max ? items.slice(0, Math.max(0, max)) : items;\n  const hidden = items.slice(visible.length);\n  const hiddenNames = hidden\n    .map((item) => (item.props as { name?: unknown }).name)\n    .filter((value): value is string => typeof value === \"string\");\n\n  return (\n    <GroupContext.Provider value={{ size, grouped: true }}>\n      <div role=\"group\" aria-label={label} data-slot=\"avatar-group\" className={cx(\"flex items-center\", sizes[size].overlap, className)} {...props}>\n        {visible}\n        {hidden.length > 0 ? (\n          <span\n            role=\"img\"\n            aria-label={`${hidden.length} more${hiddenNames.length ? `: ${hiddenNames.join(\", \")}` : \"\"}`}\n            title={hiddenNames.length ? hiddenNames.join(\", \") : undefined}\n            className={cx(\n              \"relative inline-flex shrink-0 items-center justify-center rounded-full font-medium tabular-nums select-none\",\n              \"bg-white text-zinc-600 ring-2 ring-white dark:bg-black dark:text-zinc-300 dark:ring-black\",\n              \"after:pointer-events-none after:absolute after:inset-0 after:rounded-full after:border after:border-zinc-950/12 dark:after:border-white/15\",\n              sizes[size].box,\n            )}\n          >\n            <span aria-hidden=\"true\">+{hidden.length}</span>\n          </span>\n        ) : null}\n      </div>\n    </GroupContext.Provider>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { Avatar, AvatarGroup } from \"@/components/shaken/ui/avatar\";\n\n// An inline portrait so the example works offline. Real apps pass a photo URL.\nconst portrait =\n  \"data:image/svg+xml;utf8,\" +\n  encodeURIComponent(\n    '<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><rect width=\"64\" height=\"64\" fill=\"#d6d3d1\"/><circle cx=\"32\" cy=\"26\" r=\"11\" fill=\"#78716c\"/><path d=\"M12 64c2-13 10-20 20-20s18 7 20 20z\" fill=\"#57534e\"/></svg>',\n  );\n\nconst reviewers = [\"Mara Okafor\", \"Jonas Weber\", \"Priya Raman\", \"Leo Martins\", \"Aiko Tanaka\", \"Sam Ortiz\"];\n\nfunction BotGlyph() {\n  return (\n    <svg viewBox=\"0 0 16 16\" fill=\"none\" aria-hidden=\"true\">\n      <rect x=\"2.75\" y=\"5\" width=\"10.5\" height=\"8\" rx=\"2.5\" stroke=\"currentColor\" strokeWidth=\"1.5\" />\n      <path d=\"M8 2.5V5\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n      <circle cx=\"6\" cy=\"9\" r=\"1\" fill=\"currentColor\" />\n      <circle cx=\"10\" cy=\"9\" r=\"1\" fill=\"currentColor\" />\n    </svg>\n  );\n}\n\nexport default function AvatarExample() {\n  return (\n    <div className=\"grid justify-items-center gap-8\">\n      <div className=\"flex items-end gap-4\">\n        <Avatar size=\"xs\" name=\"Mara Okafor\" />\n        <Avatar size=\"sm\" name=\"Jonas Weber\" status=\"online\" />\n        <Avatar size=\"md\" name=\"Priya Raman\" src={portrait} status=\"away\" />\n        <Avatar size=\"lg\" name=\"Release bot\" fallback={<BotGlyph />} status=\"working\" />\n        <Avatar size=\"xl\" name=\"Acme Labs\" shape=\"square\" />\n      </div>\n      <div className=\"flex items-center gap-3\">\n        <AvatarGroup label=\"Reviewers\" max={4}>\n          {reviewers.map((name) => (\n            <Avatar key={name} name={name} />\n          ))}\n        </AvatarGroup>\n        <span className=\"text-sm text-zinc-600 dark:text-zinc-400\">6 reviewers on this run</span>\n      </div>\n    </div>\n  );\n}\n"
  }
}
