Avatar

Avatars represent people or entities with an image or initials fallback. Use them in user lists, comments, profiles, and anywhere you need to identify a person visually.

Interactive preview

Toggle between image and initials fallback.

Size

Initials

Use image

Props

Prop	Type	Default	Description
size	"sm" \| "md" \| "lg" \| "xl"	"md"	Avatar dimensions. sm = 32px, md = 40px, lg = 48px, xl = 64px.
src	string	—	Image URL. If omitted, falls back to initials.
initials	string	—	Fallback text (max 2 characters) when no image is provided.
alt	string	""	Accessible label for the avatar.
className	string	""	Additional Tailwind classes.
...props	ImgHTMLAttributes<HTMLImageElement>	—	Standard image attributes when src is provided.

Installation

Install packages

pnpm add @akanaka-design/components @akanaka-design/tokens

Styles (app root)

import "@akanaka-design/tokens/css";
import "@akanaka-design/components/styles.css";

Usage

Basic usage

import { Avatar } from "@akanaka-design/components";

export function Example() {
  return (
    <Avatar 
      src="https://i.pravatar.cc/150?u=jane" 
      alt="Jane Doe" 
    />
  );
}

With initials

When no image is available, display initials as a fallback:

With initials

<Avatar initials="JD" alt="Jane Doe" />

Sizes

<Avatar initials="JD" size="sm" />
<Avatar initials="JD" size="md" />
<Avatar initials="JD" size="lg" />
<Avatar initials="JD" size="xl" />

Avatar group

Stack avatars with negative margin for a grouped appearance:

Avatar group

<div className="flex -space-x-2">
  <Avatar src="https://i.pravatar.cc/150?u=1" alt="User 1" />
  <Avatar src="https://i.pravatar.cc/150?u=2" alt="User 2" />
  <Avatar src="https://i.pravatar.cc/150?u=3" alt="User 3" />
  <Avatar initials="+5" />
</div>

Guidelines

When to use

User profiles and account menus
Comment threads and activity feeds
Team member lists
Anywhere a person or entity needs visual identification

When not to use

Logos or brand icons — use an image or icon component
Decorative imagery — use a standard image

Content

Always provide meaningful alt text
Use 1–2 character initials (first name + last name)
Prefer real photos when available for better recognition