{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "avatar",
  "type": "registry:ui",
  "title": "Avatar",
  "description": "An accessible React avatar for Next.js and Tailwind CSS: a picture or initials in three sizes, alone or in an overlapping group, built on Radix Avatar.",
  "author": "FewTone <https://fewtone.com>",
  "dependencies": [
    "class-variance-authority@^0.7.1",
    "motion@^14.0.0",
    "radix-ui@^1.7.0"
  ],
  "registryDependencies": [
    "https://ui.fewtone.com/r/tokens.json",
    "https://ui.fewtone.com/r/motion.json"
  ],
  "files": [
    {
      "path": "registry/fewtone/ui/avatar.tsx",
      "type": "registry:ui",
      "content": "\"use client\";\n\nimport { blur, duration, ease } from \"@/lib/motion\";\nimport { cn } from \"@/lib/utils\";\nimport { cva, type VariantProps } from \"class-variance-authority\";\nimport { animate, useReducedMotion } from \"motion/react\";\nimport { Avatar as AvatarPrimitive } from \"radix-ui\";\nimport {\n  type ComponentProps,\n  createContext,\n  type Ref,\n  type RefObject,\n  useCallback,\n  useContext,\n  useEffect,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\n\n/*\n * An avatar on Radix Avatar (owner's roadmap, 2026-10-16: \"A picture or initials, alone or in a group\"), with\n * shadcn's parts: Avatar, AvatarImage, AvatarFallback, AvatarGroup and AvatarGroupCount (\"+3\"), in three sizes.\n * - Motion (.agents/rules/motion.md): once the picture has loaded, it comes in through the blur over the initials,\n *   which stay underneath until it's sharp, so nothing pops or jumps. With reduced motion it only fades.\n * - Nothing animates on first paint: the picture comes in only when the avatar was on screen without it first\n *   (rendered on the server, or still loading). A picture that's ready on the avatar's first paint just shows.\n * - The initials speak for the picture: while they stand in, they carry its alt as their name, so a screen reader\n *   hears \"Olivia Martin\" whether or not the picture has loaded. With alt=\"\" (a name beside it) they're hidden too.\n * - Radix mounts the img only once it has loaded, and drops its own fallback that moment. So the fallback here is\n *   our own span, which the picture tells when it's fully in.\n * - In a group, a ring in the page's background colour separates the overlapping circles. The overlap follows the\n *   size, and each covered avatar's initials centre in its visible part, so two letters are never cut.\n */\n\n/** Where the picture is: not on screen, coming in over the initials, or fully in */\ntype Picture = \"none\" | \"entering\" | \"shown\";\n\nconst AvatarContext = createContext<{\n  picture: Picture;\n  setPicture: (picture: Picture) => void;\n  /** The picture's alt, which the initials carry while they stand in for it */\n  alt: string | undefined;\n  setAlt: (alt: string | undefined) => void;\n  /** Rendered on the server, so the initials were painted before the picture could load */\n  fromServer: boolean;\n} | null>(null);\n\nfunction useAvatar(part: string) {\n  const avatar = useContext(AvatarContext);\n  if (!avatar) throw new Error(`${part} must be used inside Avatar`);\n  return avatar;\n}\n\nconst subscribe = () => () => {};\n\nconst avatarVariants = cva(\"group/avatar relative flex shrink-0 overflow-hidden rounded-full select-none\", {\n  variants: {\n    size: {\n      sm: \"size-6\",\n      md: \"size-8\",\n      lg: \"size-10\",\n    },\n  },\n  defaultVariants: { size: \"md\" },\n});\n\nexport type AvatarProps = ComponentProps<typeof AvatarPrimitive.Root> & VariantProps<typeof avatarVariants>;\n\nfunction Avatar({ className, size, ...props }: AvatarProps) {\n  // While hydrating, React reads the server value (false): the avatar knows its initials were painted first\n  const hydrated = useSyncExternalStore(\n    subscribe,\n    () => true,\n    () => false,\n  );\n  const [fromServer] = useState(!hydrated);\n  const [picture, setPicture] = useState<Picture>(\"none\");\n  const [alt, setAlt] = useState<string>();\n  const value = useMemo(() => ({ picture, setPicture, alt, setAlt, fromServer }), [picture, alt, fromServer]);\n\n  return (\n    <AvatarContext.Provider value={value}>\n      <AvatarPrimitive.Root\n        data-slot=\"avatar\"\n        data-size={size ?? \"md\"}\n        className={cn(avatarVariants({ size }), className)}\n        {...props}\n      />\n    </AvatarContext.Provider>\n  );\n}\n\n/** Hands a node to our ref and to the caller's */\nfunction useMergedRef<T>(own: RefObject<T | null>, theirs?: Ref<T>) {\n  return useCallback(\n    (node: T | null) => {\n      own.current = node;\n      if (typeof theirs === \"function\") theirs(node);\n      else if (theirs) theirs.current = node;\n    },\n    [own, theirs],\n  );\n}\n\nexport type AvatarImageProps = ComponentProps<typeof AvatarPrimitive.Image>;\n\n/**\n * The picture. Radix loads it first and only then puts it on the page, so a broken or missing `src` leaves the\n * initials. Give it an `alt` with the person's name, or alt=\"\" when the name is written beside the avatar.\n */\nfunction AvatarImage({ className, alt, ref, onLoadingStatusChange, ...props }: AvatarImageProps) {\n  const { setPicture, setAlt, fromServer } = useAvatar(\"AvatarImage\");\n  const reduce = useReducedMotion() ?? false;\n  const node = useRef<HTMLImageElement | null>(null);\n  const setRef = useMergedRef(node, ref);\n  const [loaded, setLoaded] = useState(false);\n  // Whether the avatar has been on screen without its picture: then the picture comes in, rather than just\n  // being there\n  const waited = useRef(fromServer);\n  // Read when the picture arrives, so a change of preference never replays it\n  const reduceRef = useRef(reduce);\n  useEffect(() => {\n    reduceRef.current = reduce;\n  }, [reduce]);\n\n  useLayoutEffect(() => {\n    setAlt(alt);\n    return () => setAlt(undefined);\n  }, [alt, setAlt]);\n\n  // Radix reports \"loaded\" in the same commit that puts the img on the page, so this runs before it's painted\n  useLayoutEffect(() => {\n    const image = node.current;\n    if (!loaded || !image) return;\n    if (!waited.current) {\n      setPicture(\"shown\");\n      return () => setPicture(\"none\");\n    }\n    setPicture(\"entering\");\n    image.style.opacity = \"0\";\n    let done = false;\n    const controls = animate(\n      image,\n      reduceRef.current ? { opacity: [0, 1] } : { opacity: [0, 1], filter: [blur.hidden, blur.shown] },\n      { duration: duration.base, ease: ease.out },\n    );\n    controls.then(() => {\n      if (done) return;\n      done = true;\n      // No filter or inline opacity left behind (ADR 0011)\n      image.style.removeProperty(\"filter\");\n      image.style.removeProperty(\"opacity\");\n      setPicture(\"shown\");\n    });\n    return () => {\n      done = true;\n      controls.stop();\n      setPicture(\"none\");\n    };\n  }, [loaded, setPicture]);\n\n  return (\n    <AvatarPrimitive.Image\n      data-slot=\"avatar-image\"\n      ref={setRef}\n      alt={alt}\n      onLoadingStatusChange={(status) => {\n        // Loading and failing both leave the initials on screen for at least a frame\n        if (status === \"loading\" || status === \"error\") waited.current = true;\n        setLoaded(status === \"loaded\");\n        onLoadingStatusChange?.(status);\n      }}\n      className={cn(\"absolute inset-0 size-full object-cover\", className)}\n      {...props}\n    />\n  );\n}\n\nexport type AvatarFallbackProps = ComponentProps<\"span\"> & {\n  /** Wait this long before showing the initials, so a picture that loads quickly never flashes them */\n  delayMs?: number;\n};\n\n/** Initials (or an icon) shown until the picture has loaded, and instead of it when it can't */\nfunction AvatarFallback({ className, delayMs, ...props }: AvatarFallbackProps) {\n  const { picture, alt } = useAvatar(\"AvatarFallback\");\n  const [ready, setReady] = useState(delayMs === undefined);\n\n  useEffect(() => {\n    if (delayMs === undefined) return;\n    const timer = window.setTimeout(() => setReady(true), delayMs);\n    return () => window.clearTimeout(timer);\n  }, [delayMs]);\n\n  if (!ready || picture === \"shown\") return null;\n  // Standing in, it reads as the picture would. While the picture comes in over it, it's only seen.\n  const standingIn = picture === \"none\";\n  const name = standingIn && alt ? { role: \"img\", \"aria-label\": alt } : {};\n  return (\n    <span\n      data-slot=\"avatar-fallback\"\n      aria-hidden={!standingIn || alt === \"\" ? true : undefined}\n      {...name}\n      className={cn(\n        \"flex size-full items-center justify-center rounded-full bg-muted text-sm font-medium text-muted-foreground\",\n        \"group-data-[size=sm]/avatar:text-xs group-data-[size=lg]/avatar:text-base\",\n        // In a group the next circle covers this one's end edge (its overlap plus its ring), so the initials centre\n        // in the part that stays visible and are never cut\n        \"in-data-[slot=avatar-group]:group-not-last/avatar:pe-2\",\n        \"group-data-[size=sm]/avatar:in-data-[slot=avatar-group]:group-not-last/avatar:pe-1\",\n        \"group-data-[size=lg]/avatar:in-data-[slot=avatar-group]:group-not-last/avatar:pe-2.5\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\n/**\n * Avatars that overlap, each ringed in the page's background colour. A group (role=\"group\"): name it with\n * aria-label, for example \"Team\".\n */\nfunction AvatarGroup({ className, ...props }: ComponentProps<\"div\">) {\n  return (\n    // biome-ignore lint/a11y/useSemanticElements: a group of pictures, not form fields, so not a fieldset\n    <div\n      role=\"group\"\n      data-slot=\"avatar-group\"\n      className={cn(\n        // The overlap follows the size (2, 6 or 8px), small enough that two initials still fit beside it\n        \"group/avatar-group flex -space-x-1.5 has-data-[size=sm]:-space-x-0.5 has-data-[size=lg]:-space-x-2\",\n        \"*:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\n/** The last circle in a group, for the people not shown (\"+3\"). It takes the size of the avatars beside it. */\nfunction AvatarGroupCount({ className, ...props }: ComponentProps<\"span\">) {\n  return (\n    <span\n      data-slot=\"avatar-group-count\"\n      className={cn(\n        \"relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm font-medium text-muted-foreground ring-2 ring-background\",\n        \"group-has-data-[size=sm]/avatar-group:size-6 group-has-data-[size=sm]/avatar-group:text-xs\",\n        \"group-has-data-[size=lg]/avatar-group:size-10\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\nexport { Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage };\n"
    }
  ],
  "categories": [
    "display"
  ],
  "docs": "Usage and examples: https://ui.fewtone.com/components/avatar"
}
