Avatar Component

The Avatar component displays profile images, user initials, or fallback icons. Supports multiple sizes, variants, online/offline status, rings, and click interactions.

Import Component From Library

javascript

1import { Avatar } from "@neuctra/ui";

Basic Usage Code

Start with a simple avatar. The component supports images, fallback text, and various sizes and variants for different use cases.

jsx

1import { Avatar } from '@neuctra/ui';
2
3function BasicExample() {
4  return (
5    <Avatar
6      src="https://i.pravatar.cc/150?img=1"
7      alt="User avatar"
8      fallback="JD"
9    />
10  );
11}

Basic Example

Advanced Usage

Props Table

All available props for the Avatar component.

Prop	Type	Default	Description
src	string	—	Image source URL for the avatar
alt	string	"User avatar"	Accessibility label and alt text for the image
size	"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "responsive"	"md"	Size of the avatar
variant	"circular" \| "rounded" \| "square"	"circular"	Shape of the avatar
isOnline	boolean	false	Shows a green status dot (online indicator)
isOffline	boolean	false	Shows a gray status dot (offline indicator)
ring	boolean	false	Adds a ring around the avatar
fallback	string	—	Custom fallback text (initials) when image fails to load or no src is provided
onClick	() => void	—	Click handler. Makes the avatar focusable and keyboard accessible
statusPosition	"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"	"bottom-right"	Position of the status dot
className	string	""	Additional CSS classes for the avatar container
statusClassName	string	""	Additional CSS classes for the status dot
style	CSSProperties	—	Custom inline styles for the avatar container
statusStyle	CSSProperties	—	Custom inline styles for the status dot
imageClassName	string	—	Styles the rendered avatar image element.
fallbackClassName	string	—	Styles the fallback wrapper shown when there is no image.
iconClassName	string	—	Styles the default user icon shown when there is no image or initials.

Common Mistakes

<Avatar isOnline isOffline />

Do not use both isOnline and isOffline at the same time. Only one status should be active.

<Avatar ring ringColor="#10b981" />

ringColor prop does not exist. Use style or Tailwind classes to customize ring color.

<Avatar size="2xl" fallback="ABCD" />

Keep fallback initials short (max 2 characters) to prevent overflow on smaller sizes.

<Avatar src={image} fallback="JD" onClick={handleClick} />

Always provide a meaningful fallback for better UX when images fail.

Pro Tips

Use fallback to display user initials when the image fails to load.
Combine ring with custom style or Tailwind classes for colored rings.
Use isOnline for presence indicators in chat/messaging UIs.
Make avatars clickable by passing onClick — the component automatically handles keyboard accessibility.
Choose the right variant: circular for profiles, rounded for teams, square for apps/icons.
size="responsive" currently falls back to the same fixed dimensions as "md" internally — for breakpoint-based sizing, override the width/height with your own responsive Tailwind classes via className.
You can customize status dot appearance using statusClassName and statusStyle.

Frequently Asked Questions

How do I install and import the Avatar component?

Install the @neuctra/ui package, then import it with: import { Avatar } from "@neuctra/ui";

What variants and sizes does Avatar support?

Avatar supports variants: circular, rounded, square and sizes: xs, sm, md, lg, xl, 2xl, responsive. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the Avatar component accessible?

Avatar is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.