Avatar - HapplyUI

A compound avatar component with image, text, placeholder, and indicator positioning. Pair with StatusIndicator for status dots, verified badges, and more.

Installation

bunx @happlyui/cli@latest add avatar

Dependencies

npm packages

@radix-ui/react-slot

Registry dependencies

These are automatically installed when you add this component.

tv
happly-ui-utils
recursive-clone-children
status-indicator
avatar-empty-icons

Usage

import * as Avatar from "@/components/ui/avatar"
import * as StatusIndicator from "@/components/ui/status-indicator"

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator>
    <StatusIndicator.Root status="online" />
  </Avatar.Indicator>
</Avatar.Root>

Examples

Color

Avatar backgrounds in different colors: gray (default), yellow, blue, sky, purple, red, and primary.

<Avatar.Root>EW</Avatar.Root>
<Avatar.Root color="yellow">EW</Avatar.Root>
<Avatar.Root color="primary">EW</Avatar.Root>

Size

Avatars come in 9 sizes: 80 (default), 72, 64, 56, 48, 40, 32, 24, and 20.

<Avatar.Root size="48">
  <Avatar.Image src="/path/to/image.png" />
</Avatar.Root>

Text

Pass text children (e.g. initials) instead of an image.

<Avatar.Root>EW</Avatar.Root>
<Avatar.Root color="yellow">EW</Avatar.Root>

Placeholder

When no children are provided, a placeholder icon is shown. Use placeholderType to switch between user and company icons.

<Avatar.Root />
<Avatar.Root placeholderType="company" />

Status

Show user status (online, offline, busy, away) using Avatar.Indicator and StatusIndicator.

import * as StatusIndicator from '@/components/ui/status-indicator'

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator>
    <StatusIndicator.Root status="online" />
  </Avatar.Indicator>
</Avatar.Root>

Notification

Show a notification dot using Avatar.Indicator with position='top' and StatusIndicator.

import * as StatusIndicator from '@/components/ui/status-indicator'

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator position="top">
    <StatusIndicator.Root status="notification" />
  </Avatar.Indicator>
</Avatar.Root>

Brand Logo

Show a brand logo using Avatar.Indicator and StatusIndicator company variant with children.

import * as StatusIndicator from '@/components/ui/status-indicator'

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator position="bottom">
    <StatusIndicator.Root status="company">
      <img src="/path/to/logo.svg" className="h-full w-full rounded-full object-cover" />
    </StatusIndicator.Root>
  </Avatar.Indicator>
</Avatar.Root>

Verified Badge

Show a verified badge using Avatar.Indicator and StatusIndicator verified variant.

import * as StatusIndicator from '@/components/ui/status-indicator'

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator position="top">
    <StatusIndicator.Root status="verified" />
  </Avatar.Indicator>
</Avatar.Root>

Top Indicators

All top-position status indicators: verified, pin, favorite, add, remove, and notification.

import * as StatusIndicator from '@/components/ui/status-indicator'

<Avatar.Root>
  <Avatar.Image src="/path/to/image.png" />
  <Avatar.Indicator position="top">
    <StatusIndicator.Root status="pin" />
  </Avatar.Indicator>
</Avatar.Root>

Custom Placeholder

Pass a custom ReactNode via the placeholder prop to replace the default icon while keeping the avatar container styling.

<Avatar.Root
  placeholder={<RiBuildingLine className="w-10 h-10" />}
  color="primary"
/>
<Avatar.Root
  placeholder={<RiBuildingLine className="w-8 h-8" />}
  color="primary"
  size="64"
/>

Square Rounded

Override the default circular shape by passing a rounded className to Avatar.Root. The image inherits the rounding automatically. Use rounded-lg for larger sizes and rounded-md for smaller ones.

<Avatar.Root className="rounded-lg">
  <Avatar.Image src="/path/to/image.png" />
</Avatar.Root>

As Link

Use the asChild prop with Radix Slot to render the avatar as a link or other element.

<Avatar.Root asChild>
  <a href="#">
    <Avatar.Image src="/path/to/image.png" />
  </a>
</Avatar.Root>

API Reference

Avatar.Root

The main avatar container component.

Prop	Type	Default	Description
`size`	`'80' \| '72' \| '64' \| '56' \| '48' \| '40' \| '32' \| '24' \| '20'`	`'80'`	The size of the avatar in pixels
`color`	`'gray' \| 'yellow' \| 'blue' \| 'sky' \| 'purple' \| 'red' \| 'primary'`	`'gray'`	The background color
`placeholderType`	`'user' \| 'company'`	`'user'`	The placeholder icon type when no children are provided
`placeholder`	`ReactNode`	-	Custom placeholder content rendered when no children are provided. Overrides placeholderType.
`asChild`	`boolean`	`false`	Renders as child element using Radix Slot

Avatar.Image

The avatar image element.

Prop	Type	Default	Description
`src`	`string`	-	The image source URL
`asChild`	`boolean`	`false`	Renders as child element using Radix Slot

Avatar.Indicator

Positioned container for StatusIndicator overlays. Automatically scales based on avatar size.

Prop	Type	Default	Description
`position`	`'top' \| 'bottom'`	`'bottom'`	The position of the indicator