Free

Avatar React component for Tailwind CSS v4

Q: How do I install Avatar?

Run npx wingo-ui@latest add avatar. It also adds the Wingo UI items it builds on (Motion presets, Tones and UIProvider) and the npm packages @radix-ui/react-avatar, motion and lucide-react. With shadcn, run npx shadcn@latest add https://wingo-ui.com/r/avatar.json.

v1.0.0Added in 1.0.0

A React avatar: a photo that falls back to colored initials, with a status dot, five sizes, any shape and a stacked avatar group.

Photos fade in once they load; a slow photo shows its color first and the initials only after a short wait, and a broken one settles on the initials without a flash. A status dot pops in when the status changes. Hover a group, or Tab into it, and the stack fans out on a spring; the avatar under the pointer lifts. On a phone the first tap fans the group out, the next tap on an avatar or on +N opens it, and a tap outside folds it back. With avatar buttons, Tab walks the stack with a focus ring, and when +N reveals the rest in place, focus moves to the first new avatar. Screen readers hear the name and the status, and +N reads as a count.

Avatar is a free React component in the React data display components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add avatar, together with Motion presets, Tones and UIProvider and the npm packages @radix-ui/react-avatar, motion and lucide-react.

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

npx wingo-ui@latest add avatar

Usage

Import Avatar from @/components/ui/avatar.

import { Avatar, AvatarGroup } from "@/components/ui/avatar"

const team = [
  { name: "Michael Hayes", src: "/demo/mihai-ionescu.jpg" },
  { name: "Steven Grant" },
  { name: "Jessica Dunn", src: "/demo/ioana-dumitrescu.jpg" },
  { name: "Bianca Ross" },
  { name: "Andrew Porter", src: "/demo/andrei-popescu.jpg" },
]

export function ProfileHeader({ onOpenTeam }: { onOpenTeam: () => void }) {
  return (
    <div className="flex items-center gap-3 rounded-3xl bg-surface p-4 shadow-raised [--avatar-ring:var(--surface)]">
      <Avatar src="/demo/ana-pop.jpg" name="Anna Price" size="lg" status="online" statusLabels={{ online: "Available" }} />
      <div className="min-w-0 flex-1">
        <p className="text-[15px] font-semibold">Anna Price</p>
        <p className="text-[13px] text-muted-foreground">Member since 2019 · San Francisco</p>
      </div>
      <AvatarGroup items={team} max={3} size="sm" label="Team" overflowLabel={(n) => `${n} more`} onOverflowClick={onOpenTeam} />
    </div>
  )
}

Props

srcdefault ""
string
Image URL. While it loads the avatar shows its fallback color, and if it fails the initials take over. The demo uses /demo/ana-pop.jpg while this is empty; type a broken URL to see the fallback.
namedefault ""
string
The person or organization. It is the spoken label, gives the initials ("Steven Grant" becomes SG) and picks the fallback color. The demo shows Anna Price while this is empty.
altdefault ""
string
The spoken label when it should differ from name, e.g. "Anna Price, administrator". Empty uses name. The avatar is one image to screen readers: this label plus the status.
sizedefault "md"
"xs" | "sm" | "md" | "lg" | "xl" | number
24 / 32 / 40 / 48 / 64px with initials at 10 / 12 / 14 / 16 / 22px, or any number of px (initials and the status dot scale along). Five sizes on purpose: avatars live in dense lists and on profile headers.
radiusdefault "full"
"none" | "sm" | "md" | "lg" | "full"
full is a circle; sm, md and lg round 16 / 24 / 32% of the size, so every size keeps its shape. Squares suit companies and workspaces.
statusdefault "none"
"none" | "online" | "offline" | "busy" | "away"
A dot on the bottom end edge: green online, gray offline, red with a bar for busy, amber away. It pops in when it changes and is spoken after the name.
statusLabels
Partial<Record<"online" | "offline" | "busy" | "away", string>>
The spoken status. Defaults to { online: "Online", offline: "Offline", busy: "Busy", away: "Away" }.
variantdefault "soft"
"soft" | "solid"
How the fallback is painted: soft is a light tint with deep initials, solid a filled disc with white initials (black on a light custom color). Photos cover either.
colorfuldefault true
boolean
Initials on a color picked from the name: a stable hash into 12 hues, so a person keeps the same color everywhere. The initials are derived from the hue so they keep 4.5:1 in both themes. Off keeps every fallback neutral.
tonedefault "neutral"
"neutral" | "brand" | "success" | "warning" | "danger" | "info"
A fixed fallback color instead of the name hash. Any tone but neutral wins over colorful; neutral leaves the choice to colorful.
colordefault ""
string
Any CSS color for the fallback, a company or team color. Soft tints with it and derives readable initials; solid fills with it as is. Wins over tone and colorful. Leave empty to use them.
ringdefault false
boolean
A 2px ring in ringColor that cuts the avatar out of whatever it overlaps. Groups turn it on; the demo shows it where the avatar overlaps the cover.
ringColordefault ""
string
The surface behind the avatar, used for the ring and the status dot outline. Empty inherits a --avatar-ring set by a parent, else var(--background). Pass var(--surface) on panels, or set [--avatar-ring:var(--surface)] once on the panel.
fallbackDelaydefault 250
number
Milliseconds before the fallback shows while a photo loads, so fast photos never flash initials. Only applies with src: a list without photos shows its initials at once.
fallback
ReactNode
Replaces the initials and the user icon: a company logo, an icon, an emoji.
onLoadingStatusChange
(status: "idle" | "loading" | "loaded" | "error") => void
Fires as the photo loads or fails. The root also carries it as data-state.
classNames
Partial<Record<"image" | "fallback" | "status", string>>
Extra classes for the photo, the fallback and the status dot.
className
string
Extra classes for the root, merged last.

Parts

AvatarGroup
component
A stack with a +N chip. items (AvatarProps[]) or Avatar children; max = 4 before +N; total for the real count (+N = total - shown); size = "md" and radius = "full" for every avatar; overlap "sm" | "md" | "lg" (20 / 28 / 36%, default "md"); spread "hover" (default: fans out on hover, keyboard focus or a first tap; the box keeps its size and the fan overflows to the end, so leave room after it) | "always" | "never"; ringColor; onAvatarClick(index) makes avatars buttons; onOverflowClick makes +N a button; overflowLabel = n => `${n} more`; label = "People" (the group's aria-label); classNames { item, overflow }. Props: AvatarGroupProps.
getInitials
function
The first letter of the first and last word, Unicode-aware, upper-cased with the ro-RO rules by default: "émile zola" gives ÉZ, one word gives one letter, emoji and punctuation are skipped. Signature: (name: string, locale?: string) => string.
avatarColor
function
The fallback color for a name, one of 12 hues (AVATAR_COLORS). Use it to color the same person the same way in lists and charts. Signature: (name: string) => string.
AVATAR_COLORS
constant
The 12 fallback hues avatarColor picks from. The initials get an ink derived from each hue, so every one keeps 4.5:1 contrast in both themes.
AvatarProps
type
The props of Avatar, for wrappers like a user chip or a member row.

Examples

Sizes

xs to xl (24 to 64px), photo and initials; initials and the status dot scale along.

Radius

Circle to square. The corners are a share of the size, and the dot stays on the curve.

Status in a contacts list

online, away, busy and offline, spoken with custom statusLabels.

Initials palette

Ten names, ten hues from the name hash. The same person gets the same color everywhere.

Fallbacks

A broken photo settles on the initials, no name shows the user icon, fallback takes any node.

Group spread

Fans out on hover, focus or a first tap; always keeps it apart, never keeps it stacked.

Ring color

The ring cuts avatars out of the surface they sit on. Match it on panels and cards.

Soft, solid and custom colors

Tones and the name hash in both variants, any CSS color as a company mark, and a custom 56px size.

Dependencies

@radix-ui/react-avatar motion lucide-react motion tones ui-config

Files

components/ui/avatar.tsx

FAQ

Is the React Avatar component free?

Yes. The source is free and needs no account: copy it from the Code tab or install it with the CLI.

How do I install Avatar?

Run npx wingo-ui@latest add avatar. It also adds the Wingo UI items it builds on (Motion presets, Tones and UIProvider) and the npm packages @radix-ui/react-avatar, motion and lucide-react. With shadcn, run npx shadcn@latest add https://wingo-ui.com/r/avatar.json.

How does Avatar behave on phones?

On a phone the first tap fans the group out, the next tap on an avatar or on +N opens it, and a tap outside folds it back.

Used in

Listing card Avatar Upload Login Page Mobile App Home Kanban File manager Leaderboard Order tracker User Menu Data Table Deal Pipeline Sidebar

and 80 more.

More React data display components

Calendar View Code Block Comment Thread Contact card Description List Diff Viewer

All 23 React data display components

Free

Avatar React component for Tailwind CSS v4

v1.0.0Added in 1.0.0

A React avatar: a photo that falls back to colored initials, with a status dot, five sizes, any shape and a stacked avatar group.

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

npx wingo-ui@latest add avatar

Usage

Import Avatar from @/components/ui/avatar.

import { Avatar, AvatarGroup } from "@/components/ui/avatar"

const team = [
  { name: "Michael Hayes", src: "/demo/mihai-ionescu.jpg" },
  { name: "Steven Grant" },
  { name: "Jessica Dunn", src: "/demo/ioana-dumitrescu.jpg" },
  { name: "Bianca Ross" },
  { name: "Andrew Porter", src: "/demo/andrei-popescu.jpg" },
]

export function ProfileHeader({ onOpenTeam }: { onOpenTeam: () => void }) {
  return (
    <div className="flex items-center gap-3 rounded-3xl bg-surface p-4 shadow-raised [--avatar-ring:var(--surface)]">
      <Avatar src="/demo/ana-pop.jpg" name="Anna Price" size="lg" status="online" statusLabels={{ online: "Available" }} />
      <div className="min-w-0 flex-1">
        <p className="text-[15px] font-semibold">Anna Price</p>
        <p className="text-[13px] text-muted-foreground">Member since 2019 · San Francisco</p>
      </div>
      <AvatarGroup items={team} max={3} size="sm" label="Team" overflowLabel={(n) => `${n} more`} onOverflowClick={onOpenTeam} />
    </div>
  )
}

Props

srcdefault ""
string
Image URL. While it loads the avatar shows its fallback color, and if it fails the initials take over. The demo uses /demo/ana-pop.jpg while this is empty; type a broken URL to see the fallback.
namedefault ""
string
The person or organization. It is the spoken label, gives the initials ("Steven Grant" becomes SG) and picks the fallback color. The demo shows Anna Price while this is empty.
altdefault ""
string
The spoken label when it should differ from name, e.g. "Anna Price, administrator". Empty uses name. The avatar is one image to screen readers: this label plus the status.
sizedefault "md"
"xs" | "sm" | "md" | "lg" | "xl" | number
24 / 32 / 40 / 48 / 64px with initials at 10 / 12 / 14 / 16 / 22px, or any number of px (initials and the status dot scale along). Five sizes on purpose: avatars live in dense lists and on profile headers.
radiusdefault "full"
"none" | "sm" | "md" | "lg" | "full"
full is a circle; sm, md and lg round 16 / 24 / 32% of the size, so every size keeps its shape. Squares suit companies and workspaces.
statusdefault "none"
"none" | "online" | "offline" | "busy" | "away"
A dot on the bottom end edge: green online, gray offline, red with a bar for busy, amber away. It pops in when it changes and is spoken after the name.
statusLabels
Partial<Record<"online" | "offline" | "busy" | "away", string>>
The spoken status. Defaults to { online: "Online", offline: "Offline", busy: "Busy", away: "Away" }.
variantdefault "soft"
"soft" | "solid"
How the fallback is painted: soft is a light tint with deep initials, solid a filled disc with white initials (black on a light custom color). Photos cover either.
colorfuldefault true
boolean
Initials on a color picked from the name: a stable hash into 12 hues, so a person keeps the same color everywhere. The initials are derived from the hue so they keep 4.5:1 in both themes. Off keeps every fallback neutral.
tonedefault "neutral"
"neutral" | "brand" | "success" | "warning" | "danger" | "info"
A fixed fallback color instead of the name hash. Any tone but neutral wins over colorful; neutral leaves the choice to colorful.
colordefault ""
string
Any CSS color for the fallback, a company or team color. Soft tints with it and derives readable initials; solid fills with it as is. Wins over tone and colorful. Leave empty to use them.
ringdefault false
boolean
A 2px ring in ringColor that cuts the avatar out of whatever it overlaps. Groups turn it on; the demo shows it where the avatar overlaps the cover.
ringColordefault ""
string
The surface behind the avatar, used for the ring and the status dot outline. Empty inherits a --avatar-ring set by a parent, else var(--background). Pass var(--surface) on panels, or set [--avatar-ring:var(--surface)] once on the panel.
fallbackDelaydefault 250
number
Milliseconds before the fallback shows while a photo loads, so fast photos never flash initials. Only applies with src: a list without photos shows its initials at once.
fallback
ReactNode
Replaces the initials and the user icon: a company logo, an icon, an emoji.
onLoadingStatusChange
(status: "idle" | "loading" | "loaded" | "error") => void
Fires as the photo loads or fails. The root also carries it as data-state.
classNames
Partial<Record<"image" | "fallback" | "status", string>>
Extra classes for the photo, the fallback and the status dot.
className
string
Extra classes for the root, merged last.

Parts

AvatarGroup
component
A stack with a +N chip. items (AvatarProps[]) or Avatar children; max = 4 before +N; total for the real count (+N = total - shown); size = "md" and radius = "full" for every avatar; overlap "sm" | "md" | "lg" (20 / 28 / 36%, default "md"); spread "hover" (default: fans out on hover, keyboard focus or a first tap; the box keeps its size and the fan overflows to the end, so leave room after it) | "always" | "never"; ringColor; onAvatarClick(index) makes avatars buttons; onOverflowClick makes +N a button; overflowLabel = n => `${n} more`; label = "People" (the group's aria-label); classNames { item, overflow }. Props: AvatarGroupProps.
getInitials
function
The first letter of the first and last word, Unicode-aware, upper-cased with the ro-RO rules by default: "émile zola" gives ÉZ, one word gives one letter, emoji and punctuation are skipped. Signature: (name: string, locale?: string) => string.
avatarColor
function
The fallback color for a name, one of 12 hues (AVATAR_COLORS). Use it to color the same person the same way in lists and charts. Signature: (name: string) => string.
AVATAR_COLORS
constant
The 12 fallback hues avatarColor picks from. The initials get an ink derived from each hue, so every one keeps 4.5:1 contrast in both themes.
AvatarProps
type
The props of Avatar, for wrappers like a user chip or a member row.

Examples

Sizes

xs to xl (24 to 64px), photo and initials; initials and the status dot scale along.

Radius

Circle to square. The corners are a share of the size, and the dot stays on the curve.

Status in a contacts list

online, away, busy and offline, spoken with custom statusLabels.

Initials palette

Ten names, ten hues from the name hash. The same person gets the same color everywhere.

Fallbacks

A broken photo settles on the initials, no name shows the user icon, fallback takes any node.

Group spread

Fans out on hover, focus or a first tap; always keeps it apart, never keeps it stacked.

Ring color

The ring cuts avatars out of the surface they sit on. Match it on panels and cards.

Soft, solid and custom colors

Tones and the name hash in both variants, any CSS color as a company mark, and a custom 56px size.

Dependencies

@radix-ui/react-avatar motion lucide-react motion tones ui-config

Files

components/ui/avatar.tsx

FAQ

Is the React Avatar component free?

Yes. The source is free and needs no account: copy it from the Code tab or install it with the CLI.

How do I install Avatar?

How does Avatar behave on phones?

On a phone the first tap fans the group out, the next tap on an avatar or on +N opens it, and a tap outside folds it back.

Used in

Listing card Avatar Upload Login Page Mobile App Home Kanban File manager Leaderboard Order tracker User Menu Data Table Deal Pipeline Sidebar

and 80 more.

More React data display components

Calendar View Code Block Comment Thread Contact card Description List Diff Viewer

All 23 React data display components

Avatar React component for Tailwind CSS v4

Add to a project

Usage

Props

Parts

AvatarGroup

getInitials

avatarColor

AVATAR_COLORS

AvatarProps

Examples

Sizes

Radius

Status in a contacts list

Initials palette

Fallbacks

Group spread

Ring color

Soft, solid and custom colors

Dependencies

Files

FAQ

Is the React Avatar component free?

How do I install Avatar?

How does Avatar behave on phones?

See also

Used in

More React data display components

Avatar React component for Tailwind CSS v4

Add to a project

Usage

Props

Parts

AvatarGroup

getInitials

avatarColor

AVATAR_COLORS

AvatarProps

Examples

Sizes

Radius

Status in a contacts list

Initials palette

Fallbacks

Group spread

Ring color

Soft, solid and custom colors

Dependencies

Files

FAQ

Is the React Avatar component free?

How do I install Avatar?

How does Avatar behave on phones?

See also

Used in

More React data display components