Avatar

A versatile avatar component for displaying user profile images, initials, and status indicators with dark mode support

Installation

Install the Avatar component using the nocta-ui CLI:

Terminal

npx nocta-ui add avatar

Then import the component:

Import

import { Avatar } from '@/components/ui/avatar';

Six size options are available: xs, sm, md, lg, xl, and 2xl. The default size is md.

The Avatar component supports two shape variants: circle (default) and square.

Add status indicators to show user presence: online, offline, away, or busy.

The Avatar component gracefully handles image loading failures with multiple fallback options.

Stack multiple avatars to show groups or teams.

The Avatar component accepts a className prop for custom styling:

Prop	Type	Default	Description
`src`	`string`	-	The image source URL
`alt`	`string`	`''`	Alt text for the image
`fallback`	`string`	-	Text to generate initials from, or custom initials
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`	`'md'`	The size of the avatar
`variant`	`'circle' \| 'square'`	`'circle'`	The shape variant
`status`	`'online' \| 'offline' \| 'away' \| 'busy' \| null`	`null`	Status indicator
`className`	`string`	`''`	Additional CSS classes to apply

The Avatar component also accepts all standard HTML div element props through the ...props spread operator.

The Avatar component is built with accessibility in mind:

Size	Dimensions	Best Use Case
`xs`	24×24px	Dense lists, small UI elements
`sm`	32×32px	Compact interfaces, comments
`md`	40×40px	Default size, most common use
`lg`	48×48px	User cards, prominent displays
`xl`	64×64px	Profile headers, large cards
`2xl`	80×80px	Profile pages, hero sections