Fumadocs on TanStack Start

Overview

The Avatar component displays user profile pictures with automatic fallback to colored initials when images are unavailable. It includes smart features like deterministic color generation, built-in tooltips, and support for status badge overlays.

Import

import { Avatar } from "@px-ui/core";

Usage

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="40px"
  variant="rounded"
/>

Examples

Variants

The Avatar component supports two visual variants: squared with rounded corners, and rounded for fully circular avatars.

AISquared

JDRounded

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="Acme Inc"
  size="48px"
  variant="squared"
/>

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="48px"
  variant="rounded"
/>

Initials Fallback

When no image is provided, the Avatar automatically displays initials with a color generated from the user's name. Each unique name consistently receives the same color.

JDJSRJEDMW

<Avatar name="John Doe" size="48px" variant="rounded" />
<Avatar name="Jane Smith" size="48px" variant="rounded" />
<Avatar name="Robert Johnson" size="48px" variant="rounded" />
<Avatar name="Emily Davis" size="48px" variant="rounded" />
<Avatar name="Michael Wilson" size="48px" variant="rounded" />

Sizes

Avatars can be customized to any size using the size prop with pixel values.

JD32px

JD40px

JD48px

JD64px

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="32px"
  variant="rounded"
/>

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="40px"
  variant="rounded"
/>

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="48px"
  variant="rounded"
/>

<Avatar
  imgSrc="https://github.com/shadcn.png"
  name="John Doe"
  size="64px"
  variant="rounded"
/>

With Status Badge

Wrap the Avatar in a relative container to position status badges or indicators.

<div className="relative">
  <Avatar
    imgSrc="https://github.com/shadcn.png"
    name="John Doe"
    size="48px"
    variant="rounded"
  />
  <div className="absolute bottom-0 right-0 size-3 rounded-full border-2 border-white bg-green-500" />
</div>

<div className="relative">
  <Avatar
    imgSrc="https://github.com/shadcn.png"
    name="Jane Smith"
    size="48px"
    variant="rounded"
  />
  <div className="absolute bottom-0 right-0 size-3 rounded-full border-2 border-white bg-yellow-500" />
</div>

<div className="relative">
  <Avatar
    imgSrc="https://github.com/shadcn.png"
    name="Bob Wilson"
    size="48px"
    variant="rounded"
  />
  <div className="absolute bottom-0 right-0 size-3 rounded-full border-2 border-white bg-gray-500" />
</div>

API Reference

Avatar

Displays a user avatar with image or initials fallback.

Prop	Type	Default	Description
`imgSrc`	`string \| null \| undefined`	-	Image source URL. Supports `/SIZE/` pattern for dynamic sizing
`name`	`string \| null \| undefined`	-	User name for initials fallback and tooltip display
`variant`	`"squared" \| "rounded"`	`"squared"`	Visual style variant
`size`	`${number}px`	`"100px"`	Size of the avatar in pixels
`className`	`string`	-	Additional CSS classes
`hideTooltip`	`boolean`	`false`	Disable the name tooltip on hover

Inherited Props: Inherits all props from Base UI Avatar.Root.

Avatar

On this page