Avatar
A compact identity marker for people and accounts.
pnpm dlx shadcn@latest add @uiarc/avatarLive · keyboard ready
- Showing one person next to their name, comment, or record.
- Presence in a header or list, via the online or offline status dot.
- Places where a photo may be missing and initials should stand in.
- Use avatar-group for several people with an overflow count.
- Use user-menu when the avatar is the trigger for account actions.
Installation
Add Avatar with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/avatarAdds the component and its local dependencies, and installs motion. First time? Add the @uiarc registry to components.json, or use the full URL:
example.tsx
import { Avatar } from "@/registry/components/avatar/avatar"; export function Owner() { return <Avatar name="Maya Chen" src="/people/maya.jpg" size="lg" status="online" />;}Avatar
A round portrait that falls back to initials and can show an online or offline dot.
PropTypeDefaultDescription
nameRequiredstring–Full name. Used for the accessible label and the first two initials.srcstring–Image URL rendered with next/image. Falls back to initials if it fails to load.size"sm" | "md" | "lg" | "xl""md"Diameter, from 28px to 88px.status"online" | "offline"–Adds a presence dot and appends the status to the label....propsHTMLAttributes<HTMLSpanElement>–Forwarded to the root span, including className.- The root is role="img" with an aria-label of the name plus status, such as "Maya Chen, online".
- The image and initials are decorative, so the name is read once.
- The status dot is hidden from assistive tech; the label carries the state.
- A photo still loading fades in from a soft blur; a cached one shows at once.
- The status dot pops in and out on a snappy spring.
- Reduced motion swaps the dot instantly and drops the image fade.
- Size is fixed by the size prop, from 28px to 88px, and never changes by breakpoint.
- It renders next/image with a sizes hint per size, so phones never download a larger photo than the circle shows.
- Remote src hosts must be allowed in next.config images, since the photo goes through next/image.
- A cached photo shows at once; only a still-loading photo runs the short blur fade.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use for a single person. For a row of people with an overflow count use avatar-group.
- Remote src hosts must be allowed in next.config images, since it renders next/image.
The full library index for assistants is at /llms.txt.
