# Avatar A person's picture, or their initials until it loads or when it fails. `name` is required: screen readers hear it, and the initials come from it. Built on Base UI's Avatar, so server HTML holds the initials and the picture fades in once it loads. ```tsx import { Avatar } from "@/components/ouro/avatar/avatar"; ``` ## Example ```tsx {user.name} ``` ## Use instead when - Use `AvatarGroup` instead to stack several, and `Badge` for a status label that isn't a person. ## Props Type: `AvatarProps`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `alt` | `string` | | What screen readers hear, when it should differ from `name`. Pass `alt=""` when the name is already written next to the avatar, so it isn't read twice. | | `className` | `string` | | Layout only: margins, grid placement (`ms-2`). Appearance classes warn in development; use `size`. | | `initials` | `string` | | The letters to show instead of the ones taken from `name`, such as "AdL". | | `name` (required) | `string` | | The person's or thing's name. Screen readers hear it, and the initials come from it (the first letters of the first and last words) until the image loads, or when it fails. Required, so no avatar is silent. | | `ref` | `Ref` | | Reaches the rendered element. | | `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "xs" \| "3xl"` | `"md"` | 24, 32, 40, 48, 64, 72 or 112px (`2xl` and `3xl` for profile pages); the initials grow with it. Avatar is always a circle. Inside an `AvatarGroup`, the group's size applies. | | `src` | `string` | | The image URL. Until it loads, and if it fails, the initials show. | ## Native attributes Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page. ## Don't use These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix. - `children`: Not a prop. The initials come from `name`, or pass `initials`: ``. - `fallback`: Not a prop. The initials come from `name`, or pass `initials`: ``. ## `className` is for layout only Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: Avatar merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes] Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn. Alignment classes (`text-center`) warn too: set alignment on a parent element. [^layout-classes]: test:registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > forwards a ref and lets app layout classes win)