registry:component

Avatar

v1.0.0ga

User avatar primitive with fallback initials support.

Registry Endpoint

npx shadcn@latest add @aavya/ui-avatar

One-time setup — add the @aavya registry to your components.json so branded dependencies resolve to Aavya (not stock shadcn):

"registries": { "@aavya": "https://registry-dev.aavya.com/r/{name}.json" }

Or install by full URL: npx shadcn@latest add https://registry-dev.aavya.com/r/ui-avatar.json

Live Preview

Avatar with fallback initials

Props

Avatar forwards remaining props to AvatarPrimitive.Root props.

Guidelines

Always provide an AvatarFallback (initials or an icon) — it shows when the image is missing or slow to load.
Give AvatarImage a meaningful alt, usually the person's name.
Feed it a roughly square, appropriately sized source; the component crops to a circle.

Don’t

Don't rely on the image alone — without a fallback, a failed image renders empty.
Don't put essential information only in the avatar; pair it with a visible name or label.
Don't use an avatar as a clickable control without wrapping it in a real button or link.

Accessibility

Role

Presentational image with a text fallback (handled by Radix).

Keyboard

Not interactive on its own; when used as a trigger, the wrapping control owns keyboard behaviour.

Screen reader

Announced via the AvatarImage alt; the fallback text is read when the image is absent. You provide the alt.

Focus

Not focusable unless wrapped in an interactive element.

Gotcha

An avatar used as a menu/profile trigger must be wrapped in a <button> with an aria-label — the avatar itself carries no semantics.

Usage Snippet

import { Avatar } from '@/components/ui/avatar'

export default function Example() {
  return (
    <div className="p-6">
      <Avatar />
    </div>
  )
}

Source Preview

'use client'

import * as React from 'react'

import * as AvatarPrimitive from '@radix-ui/react-avatar'

import { cn } from '@/lib/utils'

function Avatar({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Root>) {
  return (
    <AvatarPrimitive.Root
      data-slot='avatar'
      className={cn('relative flex size-8 shrink-0 overflow-hidden rounded-full', className)}
      {...props}
    />
  )
}

function AvatarImage({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Image>) {
  return (
    <AvatarPrimitive.Image data-slot='avatar-image' className={cn('aspect-square size-full', className)} {...props} />
  )
}

function AvatarFallback({ className, ...props }: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
  return (
    <AvatarPrimitive.Fallback
      data-slot='avatar-fallback'
      className={cn('bg-muted flex size-full items-center justify-center rounded-full', className)}
      {...props}
    />
  )
}

export { Avatar, AvatarImage, AvatarFallback }