ComponentsDisplayAvatar

Avatar

User profile images with fallback initials, status indicators and group stacking.

6 sizesCircle & squareStatus indicatorAvatarGroupFallback initials

Overview

User profile images with fallback initials, status indicators and group stacking.

Avatar sizes

Live preview

Initials provide a resilient fallback when no profile image is available.

AvatarExample.tsx
tsx
import { Avatar } from 'omverse-ui'
 
<Avatar name="John Doe" size="xs" />
<Avatar name="John Doe" size="sm" />
<Avatar name="John Doe" size="md" />
<Avatar name="John Doe" size="lg" />
<Avatar name="John Doe" size="xl" />
<Avatar name="John Doe" size="2xl" />

Use an avatar to identify a person or organization in compact, repeated interfaces such as tables, comments, and account menus.

Anatomy

  • Root container and spacing boundary.
  • Primary content and optional secondary metadata.
  • State indicators and utility affordances (icons, badges, controls).
  • Optional helper text, grouping, and behavioral wrappers.

When to use

  • Choose Avatar when a repeated, structured interaction is required.
  • Use it for clear, consistent operations across similar surfaces.
  • Use in forms, lists, and action workflows where clarity matters.

When not to use

  • Do not use only for decorative layout without interaction meaning.
  • Avoid duplicating the same behavior without distinct user context.
  • Prefer simpler HTML or textual content for static, non-interactive labels.

Variants

Component variants should be documented by API props and examples below.

States

Common states include idle, active, disabled, focused, and loading/pending states where applicable.

Behavior

Behavior should remain deterministic and keyboard-friendly, with clear visual feedback for every state transition.

Accessibility

  • Use semantic structure and visible labels whenever possible.
  • Preserve keyboard navigation and focus visibility.
  • Announce status and changes when context requires it.

Content guidelines

  • Prefer short, clear labels.
  • Keep content actions scannable and outcome-oriented.
  • Use consistent wording across similar components.

Examples

Sizes

Live preview

6 sizes from xs to 2xl — fallback to initials when no image is provided

App.tsx
tsx
import { Avatar } from 'omverse-ui'
 
<Avatar name="John Doe" size="xs" />
<Avatar name="John Doe" size="sm" />
<Avatar name="John Doe" size="md" />
<Avatar name="John Doe" size="lg" />
<Avatar name="John Doe" size="xl" />
<Avatar name="John Doe" size="2xl" />

All sizes with image

Live preview

Same 6 sizes with a real image src

JohnJohnJohnJohnJohnJohn
App.tsx
tsx
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="xs" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="sm" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="md" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="lg" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="xl" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="2xl" />

With image

Live preview

Automatically falls back to initials if the image fails to load

John DoeJane SmithBob Lee
App.tsx
tsx
<Avatar src="https://i.pravatar.cc/150?img=1" name="John Doe" size="md" />
<Avatar src="https://i.pravatar.cc/150?img=5" name="Jane Smith" size="md" />
<Avatar src="https://i.pravatar.cc/150?img=3" name="Bob Lee" size="md" />

Fallback initials

Live preview

Generates initials from the name prop — JD, AW, BL, SC

App.tsx
tsx
<Avatar name="John Doe" size="md" />
<Avatar name="Alice Wang" size="md" />
<Avatar name="Bob Lee" size="md" />
<Avatar name="Sarah Connor" size="md" />

Shape

Live preview

Circle (default) or square with size-appropriate border radius

App.tsx
tsx
<Avatar name="John Doe" size="md" shape="circle" />
<Avatar name="John Doe" size="md" shape="square" />

Square shape

Live preview

Square shape across sizes — works with initials and images

John
App.tsx
tsx
<Avatar name="John Doe" size="sm" shape="square" />
<Avatar name="John Doe" size="md" shape="square" />
<Avatar name="John Doe" size="lg" shape="square" />
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" size="lg" shape="square" />

Status indicators

Live preview

Online (green), offline (gray), away (amber) and busy (red)

App.tsx
tsx
<Avatar name="John Doe" size="md" status="online" />
<Avatar name="John Doe" size="md" status="offline" />
<Avatar name="John Doe" size="md" status="away" />
<Avatar name="John Doe" size="md" status="busy" />

All status indicators

Live preview

Status dots at lg size for better visibility

App.tsx
tsx
<Avatar name="John" size="lg" status="online" />
<Avatar name="Jane" size="lg" status="offline" />
<Avatar name="Bob" size="lg" status="away" />
<Avatar name="Alice" size="lg" status="busy" />

Avatar group

Live preview

Stacks avatars with overlap — extras beyond max collapse into a count badge

JohnJaneBob+2
App.tsx
tsx
import { Avatar, AvatarGroup } from 'omverse-ui'
 
<AvatarGroup max={3}>
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" />
<Avatar src="https://i.pravatar.cc/150?img=2" name="Jane" />
<Avatar src="https://i.pravatar.cc/150?img=3" name="Bob" />
<Avatar src="https://i.pravatar.cc/150?img=4" name="Alice" />
<Avatar src="https://i.pravatar.cc/150?img=5" name="Tom" />
</AvatarGroup>

Avatar group sizes

Live preview

Group size prop is passed to all child avatars

JohnJaneBobAlice+1
JohnJaneBobAlice+1
App.tsx
tsx
<AvatarGroup max={4} size="sm">
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" />
<Avatar src="https://i.pravatar.cc/150?img=2" name="Jane" />
<Avatar src="https://i.pravatar.cc/150?img=3" name="Bob" />
<Avatar src="https://i.pravatar.cc/150?img=4" name="Alice" />
<Avatar src="https://i.pravatar.cc/150?img=5" name="Tom" />
</AvatarGroup>
<AvatarGroup max={4} size="md">
<Avatar src="https://i.pravatar.cc/150?img=1" name="John" />
<Avatar src="https://i.pravatar.cc/150?img=2" name="Jane" />
<Avatar src="https://i.pravatar.cc/150?img=3" name="Bob" />
<Avatar src="https://i.pravatar.cc/150?img=4" name="Alice" />
<Avatar src="https://i.pravatar.cc/150?img=5" name="Tom" />
</AvatarGroup>

Props / API

Api Props

Props

PropTypeDefaultDescription
namestring—Used for fallback initials and aria-label
srcstringundefinedImage URL — falls back to initials on error
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl''md'Avatar size
shape'circle' | 'square''circle'Avatar shape
status'online' | 'offline' | 'away' | 'busy'undefinedStatus indicator dot
color'default' | 'secondary' | 'success' | 'warning' | 'error' | 'info'undefinedBackground color for initials fallback
clickablebooleanfalseAdds hover/focus styles and role="button"