Avatar

Avatars are used to represent users or entities with profile pictures, initials, or fallback icons. They support various sizes, shapes, colors, and status indicators.

import { Avatar } from "@ninna-ui/primitives"

pnpm add @ninna-ui/primitives

Requires @ninna-ui/core (auto-installed) + CSS setup.

View source

Usage

Import and use the Avatar component in your application.

import { Avatar , Code } from "@ninna-ui/primitives";

export default function Example() {
  return (
    <Avatar
      src="/user-avatar.jpg"
      alt="John Doe"
      name="John Doe"
      size="md"
    />
  );
}

Basic

Basic avatar examples with image, initials, and fallback icon.

JDJS

Sizes

Avatars in different sizes from xs to xl.

Xxs

Ssm

Mmd

Llg

Xxl

Colors

Different color themes for the fallback background.

NPSAISWD

Shapes

Circle and square shapes with different border radius options.

Ccircle

Ssquare (none)

Ssquare (sm)

Msquare (md)

Lsquare (lg)

Fallback

Different fallback options: initials, icon, custom content, or when image fails to load.

JDInitials

ASingle Letter

Icon

🎨Custom

Image Error

With Ring

Avatars with a colored ring border.

JAMRTA

Avatar Group

Group multiple avatars with overlap and overflow indicator.

Basic Group

With Max Limit (max=3)

JDJSBW+2

Different Sizes

ABC

import { Avatar, AvatarGroup , Code } from "@ninna-ui/primitives";

export default function Example() {
  return (
    <AvatarGroup max={3}>
      <Avatar name="John Doe" color="primary" />
      <Avatar name="Jane Smith" color="secondary" />
      <Avatar name="Bob Wilson" color="success" />
      <Avatar name="Alice Brown" color="info" />
    </AvatarGroup>
  );
}

Use Cases

Real-world examples of avatar usage in different contexts.

John Doe

Software Engineer

Online

Comment Thread

Alice Brown

Great work on this feature!

Bob Wilson

Thanks! Happy to help.

Team Members

JDJSBWAB+2

6 team members

Notifications

Sarah mentioned you in a comment

2 minutes ago

Mike approved your request

1 hour ago

With Badge

APro

✓

API Reference

Complete list of props for the Avatar components.

Avatar Props

Props

Prop	Type	Default	Description
`src`	`string`	-	Image source URL for the avatar
`alt`	`string`	-	Alternative text for the image
`name`	`string`	-	Name used to generate initials fallback (e.g., 'John Doe' → 'JD')
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size of the avatar
`shape`	`'circle' \| 'square'`	`'circle'`	Shape of the avatar
`radius`	`'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'`	`'md'`	Border radius when shape is 'square'
`color`	`'neutral' \| 'primary' \| 'secondary' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'`	`'neutral'`	Color theme for fallback background
`showRing`	`boolean`	`false`	Show a colored ring around the avatar
`ringColor`	`Color`	-	Ring color (defaults to color prop)
`fallback`	`React.ReactNode`	-	Custom fallback content when image fails or no src
`showFallbackIcon`	`boolean`	`false`	Show fallback icon instead of initials
`loading`	`'eager' \| 'lazy'`	`'lazy'`	Image loading attribute
`className`	`string`	-	Additional CSS classes

AvatarGroup Props

Props

Prop	Type	Default	Description
`max`	`number`	-	Maximum number of avatars to show before overflow indicator
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size for all avatars in the group
`spacing`	`'tight' \| 'normal' \| 'loose'`	`'normal'`	Spacing between avatars (overlap amount)
`children*`	`React.ReactNode`	-	Avatar components to display in the group
`className`	`string`	-	Additional CSS classes

Accessibility

Avatar has role="img" for proper semantic meaning
Uses aria-label with alt text or name for screen readers
AvatarGroup has role="group" with descriptive label
Images use loading="lazy" by default for performance
Fallback content is properly announced to screen readers
Overflow count in groups is accessible with proper labeling