Manicat UI

Avatar

A compact identity marker for people and accounts.

identitypeople
Preview
Avatar preview

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.

shadcn CLI

Also installs (1)

  • manicat-foundation
Manual install(+)
registry.jsonjson
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "avatar",
  "type": "registry:ui",
  "title": "Avatar",
  "description": "A compact identity marker for people and accounts.",
  "categories": [
    "data"
  ],
  "dependencies": [
    "motion"
  ],
  "registryDependencies": [
    "https://manicat.viraza.net/r/manicat-foundation.json"
  ],
  "files": [
    {
      "path": "registry/components/avatar/avatar.tsx",
      "type": "registry:component",
      "target": "@components/manicat/avatar/avatar.tsx"
    },
    {
      "path": "registry/components/avatar/avatar.module.css",
      "type": "registry:component",
      "target": "@components/manicat/avatar/avatar.module.css"
    }
  ],
  "docs": "Docs and live preview: https://uiarc.dev/components/avatar",
  "meta": {
    "tier": "free",
    "kind": "component",
    "docs": "https://manicat.viraza.net/components/avatar",
    "markdown": "https://uiarc.dev/components/avatar/markdown",
    "tags": [
      "identity",
      "people"
    ]
  }
}

Usage

Install the component, then copy this into your app. Change the content and the props to fit your screen.

example.tsxtsx
"use client";

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

export function AvatarExample() {
  return (
    <div className="flex items-center gap-3">
      <Avatar name="Elia Kuratli" size="sm" />
      <Avatar name="Ada Lovelace" status="online" />
      <Avatar name="Grace Hopper" size="lg" />
      <Avatar name="Alan Turing" size="xl" status="offline" />
    </div>
  );
}

Examples

Real screens rather than isolated props. Switch to Code to copy a whole example into your project.

Presence Sizes and online/offline status as they appear in a member list.

Presence Sizes and online/offline status as they appear in a member list. preview

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 ArcProvider) phones never download a larger photo than the circle shows.

Performance

  • The photo is a plain lazy img by default. Pass next/image through ArcProvider 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 ArcProvider from @/components/arc/lib/arc-provider: <ArcProvider image={Image}>. With next/image, remote hosts must be allowed in next.config images.