Avatar

A user image with a text or icon fallback when it's missing.

Usage

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

<Avatar>
  <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
  <AvatarFallback>SJ</AvatarFallback>
</Avatar>

Avatar represents a person or entity. Compose it from its parts, all under @appica/ui-react/avatar:

Avatar — the root that sets size and shape and clips its children to the rounded silhouette.
AvatarImage — the photo. Base UI preloads the src and only swaps it in once it has loaded, so a broken or slow image never flashes.
AvatarFallback — what shows until (or unless) the image loads: initials or an icon.
AvatarBadge — an optional status dot in the corner.
AvatarGroup — a wrapper that overlaps a row of avatars and forwards a shared size/shape.

The whole component is sized in em, so a single size (a preset or a pixel number) scales the image, fallback text, and status badge together.

Examples

Default

An AvatarImage with an AvatarFallback beneath it. The image is shown once loaded; until then — or if it fails — the fallback initials take its place.

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarDefault() {
  return (
    <Avatar size="lg">
      <AvatarImage src="/avatars/01.jpg" alt="Sarah Jenkins" />
      <AvatarFallback>SJ</AvatarFallback>
    </Avatar>
  )
}

Fallback

When the image is missing, still loading, or fails to load, the AvatarFallback renders instead. Use initials for people, or an icon for a generic placeholder.

SJMR

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { UserFilled } from '@appica/icons-react'

export default function AvatarFallbackExample() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg">
        <AvatarImage src="/avatars/does-not-exist.jpg" alt="Sarah Jenkins" />
        <AvatarFallback>SJ</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar size="lg">
        <AvatarFallback>
          <UserFilled />
        </AvatarFallback>
      </Avatar>
    </div>
  )
}

Sizes

Seven presets run from 2xs to 2xl. Because the avatar is sized in em, the fallback text and status badge scale along with the image.

DRDRDRDRDRDR

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

const sizes = ['2xs', 'xs', 'sm', 'md', 'lg', 'xl'] as const

export default function AvatarSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-4">
      {sizes.map((size) => (
        <Avatar key={size} size={size}>
          <AvatarImage src="/avatars/02.jpg" alt="Daniel Reyes" />
          <AvatarFallback>DR</AvatarFallback>
        </Avatar>
      ))}
    </div>
  )
}

Custom size

Pass a number to size for an exact pixel dimension when a preset doesn't fit — say to match a specific line height. It drives the root's font-size, so everything inside still scales proportionally.

ATATAT

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarCustomSize() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size={28}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
      <Avatar size={44}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
      <Avatar size={72}>
        <AvatarImage src="/avatars/04.jpg" alt="Ava Thompson" />
        <AvatarFallback>AT</AvatarFallback>
      </Avatar>
    </div>
  )
}

Shape

shape="circle" (the default) renders a full circle; shape="rounded" uses a squircle-style rounded square for a more app-like look.

MRMR

import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarShape() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg" shape="circle">
        <AvatarImage src="/avatars/03.jpg" alt="Mateo Rossi" />
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
      <Avatar size="lg" shape="rounded">
        <AvatarImage src="/avatars/03.jpg" alt="Mateo Rossi" />
        <AvatarFallback>MR</AvatarFallback>
      </Avatar>
    </div>
  )
}

Status badge

Drop an AvatarBadge inside the avatar for a corner status dot. Add animate for a gentle pulsing ping that draws the eye to an online indicator, and recolor it with a text-* class.

LHEGLM

import { Avatar, AvatarImage, AvatarFallback, AvatarBadge } from '@appica/ui-react/avatar'

export default function AvatarStatus() {
  return (
    <div className="flex items-center gap-4">
      <Avatar size="lg">
        <AvatarImage src="/avatars/08.jpg" alt="Liam Hudson" />
        <AvatarFallback>LH</AvatarFallback>
        <AvatarBadge />
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="/avatars/09.jpg" alt="Emma Garcia" />
        <AvatarFallback>EG</AvatarFallback>
        <AvatarBadge animate />
      </Avatar>
      <Avatar size="lg">
        <AvatarImage src="/avatars/06.jpg" alt="Lucas Müller" />
        <AvatarFallback>LM</AvatarFallback>
        <AvatarBadge className="text-foreground-subtle" />
      </Avatar>
    </div>
  )
}

Avatar group

AvatarGroup overlaps a row of avatars and rings each one with the background color so they read as a stack. It forwards a shared size/shape to its children, and any non-image avatar — like a +5 counter — sits in the same rhythm.

SJLHMRAT+5

import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from '@appica/ui-react/avatar'

const people = [
  { src: '/avatars/01.jpg', alt: 'Sarah Jenkins', initials: 'SJ' },
  { src: '/avatars/02.jpg', alt: 'Liam Hudson', initials: 'LH' },
  { src: '/avatars/03.jpg', alt: 'Mateo Rossi', initials: 'MR' },
  { src: '/avatars/04.jpg', alt: 'Ava Thompson', initials: 'AT' },
]

export default function AvatarGroupExample() {
  return (
    <AvatarGroup size="md">
      {people.map((person) => (
        <Avatar key={person.src}>
          <AvatarImage src={person.src} alt={person.alt} />
          <AvatarFallback>{person.initials}</AvatarFallback>
        </Avatar>
      ))}
      <Avatar>
        <AvatarFallback className="text-foreground-muted text-sm">+5</AvatarFallback>
      </Avatar>
    </AvatarGroup>
  )
}

Next.js Image

To serve optimized images, pass a Next.js <Image> to AvatarImage's render prop. The wrapper lifts the src so Base UI's preloader still drives the fallback, and applies its own object-cover and rounded-corner classes to the rendered <Image>. Give the Image a width/height that matches the avatar's pixel size.

import Image from 'next/image'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'

export default function AvatarNextImage() {
  return (
    <Avatar size="xl">
      <AvatarImage render={<Image src="/avatars/08.jpg" alt="Liam Hudson" width={64} height={64} />} />
      <AvatarFallback>LH</AvatarFallback>
    </Avatar>
  )
}

Loading animation

AvatarFallback renders until the image finishes loading, so dropping a Skeleton inside it gives a shimmering placeholder that Base UI swaps for the photo automatically — no extra state needed. Press Reload to fetch a fresh copy and watch it again.

'use client'

import { useState, useEffect } from 'react'
import { Avatar, AvatarImage, AvatarFallback } from '@appica/ui-react/avatar'
import { Skeleton } from '@appica/ui-react/skeleton'
import { Button } from '@appica/ui-react/button'

export default function AvatarLoading() {
  const [src, setSrc] = useState<string>()
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    setSrc(undefined)
    // Demo only: defer the image ~2.5s so the loading skeleton stays visible.
    const id = setTimeout(() => setSrc(`/avatars/09.jpg?reload=${nonce}`), 2500)
    return () => clearTimeout(id)
  }, [nonce])

  return (
    <div className="flex flex-col items-center gap-4">
      <Avatar size="xl" className="bg-transparent">
        <AvatarImage src={src} alt="Emma Garcia" />
        <AvatarFallback>
          <Skeleton className="size-full rounded-[inherit]" />
        </AvatarFallback>
      </Avatar>
      <Button variant="outline" size="sm" onClick={() => setNonce((n) => n + 1)} disabled={!src}>
        Reload
      </Button>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The status badge moves to the start (right) corner and the group stacks from the right, because both are expressed with logical properties. For setup details and caveats, see the RTL guide.

SJLHMR

API reference

Avatar wraps Base UI's Avatar. Each part forwards ref and its remaining attributes to the matching Base UI primitive — AvatarImage preloads src and only mounts the image once it resolves. AvatarBadge and AvatarGroup are Appica additions. See the Base UI docs for the complete API.

Avatar

The root. Renders a <span> that sizes and clips its children.

Prop	Type	Default	Description
`size`	`'2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| number`	`'md'`	A preset scale, or a pixel number for an exact size.
`shape`	`'circle' \| 'rounded'`	`'circle'`	Full circle or rounded square.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the root element, or compose it with another component.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AvatarImage

The photo. Renders an <img> (or the render element) once the source has loaded.

Prop	Type	Default	Description
`src`	`string`	—	Image URL. Lifted from the `render` element when omitted.
`alt`	`string`	—	Alternative text describing the person/entity.
`onLoadingStatusChange`	`(status: 'idle' \| 'loading' \| 'loaded' \| 'error') => void`	—	Fires as the image moves through its loading lifecycle.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Swap the `<img>` for another element — e.g. a Next.js `<Image>`.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AvatarFallback

Shown until — or unless — the image loads. Renders a <span>.

Prop	Type	Default	Description
`delay`	`number`	—	Milliseconds to wait before showing the fallback (avoids a flash on fast loads).
`children`	`ReactNode`	—	Initials or an icon. Text is auto-shrunk; an `svg` is shown at full size.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the fallback element.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

AvatarBadge

An optional status dot in the corner. Renders a <span>.

Prop	Type	Default	Description
`animate`	`boolean`	`false`	Add a pulsing ping behind the dot (skipped under reduced motion).
`className`	`string`	—	Extra classes — recolor with a `text-*` class.

AvatarGroup

Overlaps a row of avatars and forwards a shared size/shape. Renders a <div>.

Prop	Type	Default	Description
`size`	`Avatar['size']`	—	Default size applied to child avatars that don't set their own.
`shape`	`Avatar['shape']`	—	Default shape applied to child avatars that don't set their own.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Stack the avatars in a row or a column.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

A child Avatar's own size/shape always wins over the group default.

Accessibility

Give every meaningful AvatarImage an alt that names the person or entity. For a purely decorative avatar, use alt="".
The AvatarFallback text (initials) is visible content, so it's announced; for an icon-only fallback, the icon is decorative — make sure the surrounding context names the user.
AvatarBadge is a visual status indicator. If the status is important, convey it in text nearby (e.g. "Online") rather than relying on the dot's color alone.
In an AvatarGroup, each avatar keeps its own accessible name; consider an aria-label on the group (e.g. "Project members") and visible text for any +N overflow count.
The status badge's pulsing animation is skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Avatar

Usage

Examples

Default

Fallback

Sizes

Custom size

Shape

Status badge

Avatar group

Next.js Image

Loading animation

RTL

API reference

Avatar

AvatarImage

AvatarFallback

AvatarBadge

AvatarGroup

Accessibility