Skip to main content

Avatar

Display user profiles. Robust fallbacks. Build trust visually.

@figueroaignacioUS
default.tsx
1'use client';
2
3import { Avatar } from '@/components/ui/avatar';
4
5export function Default() {
6 return (
7 <Avatar>
8 <Avatar.Image src="https://github.com/figueroaignacio.png" alt="@figueroaignacio" />
9 <Avatar.Fallback>US</Avatar.Fallback>
10 </Avatar>
11 );
12}

Installation

pnpm dlx nachui add avatar

Anatomy

1import { Avatar } from '@/components/ui/avatar';
1<Avatar>
2 <Avatar.Image src="https://github.com/shadcn.png" />
3 <Avatar.Fallback>CN</Avatar.Fallback>
4</Avatar>

Variants

Default

@figueroaignacioUS
default.tsx
1'use client';
2
3import { Avatar } from '@/components/ui/avatar';
4
5export function Default() {
6 return (
7 <Avatar>
8 <Avatar.Image src="https://github.com/figueroaignacio.png" alt="@figueroaignacio" />
9 <Avatar.Fallback>US</Avatar.Fallback>
10 </Avatar>
11 );
12}

Sizes

You can change the size via the size prop.
@figueroaignacioFI@figueroaignacioFI@figueroaignacioFI
sizes.tsx
1'use client';
2
3import { Avatar } from '@/components/ui/avatar';
4
5const sizes = [
6 { size: 'sm' as const, fallback: 'FI' },
7 { size: 'md' as const, fallback: 'FI' },
8 { size: 'lg' as const, fallback: 'FI' },
9];
10
11export function Sizes() {
12 return (
13 <div className="flex items-center gap-4">
14 {sizes.map((avatar) => (
15 <Avatar key={avatar.size} size={avatar.size}>
16 <Avatar.Image src="https://github.com/figueroaignacio.png" alt="@figueroaignacio" />
17 <Avatar.Fallback>{avatar.fallback}</Avatar.Fallback>
18 </Avatar>
19 ))}
20 </div>
21 );
22}

With Fallback

If the image takes time to load or fails, the fallback text (usually initials) will be displayed.
@figueroaignacioFIFI
with-fallback.tsx
1'use client';
2
3import { Avatar } from '@/components/ui/avatar';
4
5const avatars = [
6 {
7 src: 'https://github.com/figueroaignacio.pn', // broken link — tests image fallback
8 alt: '@figueroaignacio',
9 fallback: 'FI',
10 fallbackClassName: undefined,
11 },
12 {
13 src: undefined, // no image — tests text fallback
14 alt: undefined,
15 fallback: 'FI',
16 fallbackClassName: 'bg-primary text-primary-foreground',
17 },
18];
19
20export function WithFallback() {
21 return (
22 <div className="flex gap-4">
23 {avatars.map((avatar, i) => (
24 <Avatar key={i}>
25 {avatar.src && <Avatar.Image src={avatar.src} alt={avatar.alt ?? ''} />}
26 <Avatar.Fallback className={avatar.fallbackClassName}>{avatar.fallback}</Avatar.Fallback>
27 </Avatar>
28 ))}
29 </div>
30 );
31}

Avatar Group

Display multiple avatars overlapping using Avatar.Group.
@figueroaignacioFI@nicvazquezdevNV@ManuZarragaMZ+3
avatar-group.tsx
1'use client';
2
3import { Avatar } from '@/components/ui/avatar';
4
5const avatars = [
6 { src: 'https://github.com/figueroaignacio.png', alt: '@figueroaignacio', fallback: 'FI' },
7 { src: 'https://github.com/nicvazquezdev.png', alt: '@nicvazquezdev', fallback: 'NV' },
8 { src: 'https://github.com/ManuZarraga.png', alt: '@ManuZarraga', fallback: 'MZ' },
9];
10
11export function AvatarGroup() {
12 return (
13 <Avatar.Group>
14 {avatars.map((avatar) => (
15 <Avatar key={avatar.alt}>
16 <Avatar.Image src={avatar.src} alt={avatar.alt} />
17 <Avatar.Fallback>{avatar.fallback}</Avatar.Fallback>
18 </Avatar>
19 ))}
20 <Avatar>
21 <Avatar.Fallback className="bg-muted text-muted-foreground">+3</Avatar.Fallback>
22 </Avatar>
23 </Avatar.Group>
24 );
25}

API Reference

Avatar

PropTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Visual size of avatar
classNamestring-Additional CSS classes
Found something to improve?

Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.

Create an Issue