Avatar

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/avatar
• Markdown: https://ui.xzero.co.uk/components/avatar/markdown
• Registry item: https://mcp.xzero.co.uk/r/avatar.json
• Source file: registry/components/avatar/avatar.tsx
• Dependencies: motion
• Keywords: identity, people, react avatar, avatar component, user avatar with initials, profile picture, avatar with status, online indicator avatar

When to use

• 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.

When not to use

• Use avatar-group for several people with an overflow count.
• Use user-menu when the avatar is the trigger for account actions.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/avatar

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { Avatar } from "@/components/xzero/avatar/avatar";

export function Owner() {
  return <Avatar name="Maya Chen" src="/people/maya.jpg" size="lg" status="online" />;
}

API reference

Avatar

A round portrait that falls back to initials and can show an online or offline dot.

Prop	Type	Default	Description
name (required)	string	–	Full name. Used for the accessible label and the first two initials.
src	string	–	Image URL. Renders a plain img, or the image component set with XzeroProvider (such as 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.
...props	HTMLAttributes<HTMLSpanElement>	–	Forwarded to the root span, including className.

Accessibility

• 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.

Motion

• 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.

Responsive behavior

• Size is fixed by the size prop, from 28px to 88px, and never changes by breakpoint.
• It passes a sizes hint per size, so with next/image (through XzeroProvider) phones never download a larger photo than the circle shows.

Performance

• The photo is a plain lazy img by default. Pass next/image through XzeroProvider to optimize it; remote hosts then need next.config images settings.
• A cached photo shows at once; only a still-loading photo runs the short blur fade.

Notes for AI

• Use for a single person. For a row of people with an overflow count use avatar-group.
• Renders a plain img, so any host works in any React app. To use next/image or your own image component, wrap the app once in XzeroProvider from @/components/xzero/lib/xzero-provider: <XzeroProvider image={Image}>. With next/image, remote hosts must be allowed in next.config images.

Related

• Avatar group: Show a team or set of contributors in a small space.
• User menu: Your account, settings, theme, and sign out behind the avatar. Opens as a bottom sheet on phones.
• Card: A contained group of related content and actions.
• Timeline: Follow what happened, newest first, grouped by day.

Also in avatars

• Badge: A small label for status, category, or metadata.
• Presence stack: Avatars of the people here now: joins pop in as the stack reflows, a counter rolls past the limit, dots show typing and idle, and hover fans it out with a gliding name label.

Guidance for AI tools

Avatar: A compact identity marker for people and accounts. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt