Introduction

Avatars identify a person or organisation in lists, headers and comment threads. When no picture is available they fall back to initials, and failing that, an icon.

Built on Radix UI's Avatar primitive, so a broken or slow image resolves to the fallback rather than showing a torn image.

Size	Box	Initials
`sm`	24px	11px
`md`	32px	12px
`lg`	40px	14px
`xl`	48px	16px

Installation

npx shadcn@latest add https://indiacn.in/r/avatar.json

import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar';

Usage

<Avatar>
<AvatarImage src="/aarav.jpg" alt="Aarav Sharma" />
<AvatarFallback>AS</AvatarFallback>
</Avatar>

Examples

Default

Picture, initials, and icon fallbacks.

SMAS

AvatarDefault

import { User } from 'lucide-react';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Indicator } from '@/components/ui/indicator';
import { Body3 } from '@/components/ui/typography';

export default function Component() {
  return (
    <div className='flex items-center gap-4'>
      <Avatar>
        <AvatarFallback>SM</AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarFallback>
          <User aria-hidden />
        </AvatarFallback>
      </Avatar>
      <Avatar>
        <AvatarImage src='/icon.svg' alt='Aarav Sharma' />
        <AvatarFallback>AS</AvatarFallback>
      </Avatar>
    </div>
  );
}

Sizes

SMMDLGXL

AvatarSizes

import { User } from 'lucide-react';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Indicator } from '@/components/ui/indicator';
import { Body3 } from '@/components/ui/typography';

export default function Component() {
  return (
    <div className='flex items-end gap-4'>
      <Avatar size='sm'>
        <AvatarFallback>SM</AvatarFallback>
      </Avatar>
      <Avatar size='md'>
        <AvatarFallback>MD</AvatarFallback>
      </Avatar>
      <Avatar size='lg'>
        <AvatarFallback>LG</AvatarFallback>
      </Avatar>
      <Avatar size='xl'>
        <AvatarFallback>XL</AvatarFallback>
      </Avatar>
    </div>
  );
}

Shapes

CIRE

AvatarShapes

import { User } from 'lucide-react';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Indicator } from '@/components/ui/indicator';
import { Body3 } from '@/components/ui/typography';

export default function Component() {
  return (
    <div className='flex items-center gap-4'>
      <Avatar shape='circular' size='lg'>
        <AvatarFallback>CI</AvatarFallback>
      </Avatar>
      <Avatar shape='rectangular' size='lg'>
        <AvatarFallback>RE</AvatarFallback>
      </Avatar>
    </div>
  );
}

With a Status Dot

UX4G's avatar has an optional 6px badge. That is the same 6px dot as Indicator, so compose the two rather than duplicating it.

The 6px status dot is an Indicator, positioned by the consumer.

AvatarWithBadge

import { User } from 'lucide-react';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Indicator } from '@/components/ui/indicator';
import { Body3 } from '@/components/ui/typography';

export default function Component() {
  return (
    <div className='flex items-center gap-6'>
      <div className='relative inline-flex'>
        <Avatar size='lg'>
          <AvatarFallback>AS</AvatarFallback>
        </Avatar>
        <Indicator
          theme='success'
          variant='dot'
          className='ring-neutral-0 absolute right-0 bottom-0 ring-2'
        />
      </div>
      <Body3 className='text-neutral-600'>
        The 6px status dot is an Indicator, positioned by the consumer.
      </Body3>
    </div>
  );
}

Accessibility

Always give AvatarImage a meaningful alt. If the avatar sits beside the person's name, alt="" is correct — repeating the name makes screen readers announce it twice.
Initials are decorative to a screen reader. Make sure the name appears in nearby text, or label the container.
A status dot carries no text. State what it means in the surrounding markup, not by colour alone.

API Reference

Avatar

Prop	Type	Default	Description
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	24, 32, 40 or 48px. Initials scale with it
`shape`	`'circular' \| 'rectangular'`	`'circular'`	Fully rounded, or 8px corners
`className`	`string`	—	Extra Tailwind classes

AvatarImage

Prop	Type	Default	Description
`src`	`string`	—	Image source
`alt`	`string`	—	Alternative text
`onLoadingStatusChange`	`(status) => void`	—	Fires as the image loads or fails

AvatarFallback

Prop	Type	Default	Description
`delayMs`	`number`	—	Wait before showing, to avoid a flash on fast connections
`children`	`ReactNode`	—	Initials or an icon. Icons are sized to the avatar automatically

Avatar

On this page