Avatar

Overview

Avatars display the first two letters of a user's name in uppercase, white text, on a dark-toned background. The background color is chosen deterministically from a palette of 9 colors using name.charCodeAt(0) % 9. This ensures the same user always gets the same color across all pages.

Sizes

xs · 24px

sm · 32px

md · 40px

lg · 48px

xl · 64px

2xl · 80px

<span class="avatar avatar-xs" style="background:#1E293B">BS</span>
<span class="avatar avatar-sm" style="background:#1E293B">BS</span>
<span class="avatar avatar-md" style="background:#1E293B">BS</span>
<span class="avatar avatar-lg" style="background:#312E81">AW</span>
<span class="avatar avatar-xl" style="background:#065F46">RP</span>

With Status Indicator

Online

Busy

Offline

<span class="avatar avatar-md" style="background:#1E293B;position:relative">
  BS
  <span class="avatar-status avatar-status-online"></span>
</span>

Avatar Group

Default group (sm)

BS AW RP DK +5

Medium group

BS AW RP +8

<div class="avatar-group">
  <span class="avatar avatar-sm" style="background:#1E293B">BS</span>
  <span class="avatar avatar-sm" style="background:#312E81">AW</span>
  <span class="avatar avatar-sm" style="background:#475569;font-size:10px">+5</span>
</div>

Square Variant

Used for logos and company avatars — not user avatars.

PT CV UD

Background Color Palette

Class	Hex Value	Index (name.charCodeAt(0) % 9)
.av-slate	#1E293B	0
.av-indigo	#312E81	1
.av-green	#065F46	2
.av-red	#7C2D12	3
.av-blue	#1E40AF	4
.av-purple	#3B0764	5
.av-teal	#134E4A	6
.av-amber	#78350F	7
.av-gray	#374151	8

AI Implementation Notes

For AI coding assistants: Avatars are always <span> elements, always circular (border-radius:50%). Initials are always the first two characters of the full name, uppercase. Background color uses:

const COLORS = ['#1E293B','#312E81','#065F46','#7C2D12','#1E40AF','#3B0764','#134E4A','#78350F','#374151']; bg = COLORS[name.charCodeAt(0) % 9]

. In avatar groups, each avatar gets border:2px solid #fff; margin-left:-8px (first child: margin-left:0). The overflow counter ("+N") uses background:#475569.

When to Use

Use Avatar when

Representing a user in tables, lists, comments
Profile headers and user chips in topbar
Avatar groups to show team members

Don't use Avatar when

Representing a company or entity — use a square variant or logo
As a standalone CTA — wrap in a button

Properties

Property	Type	Required	Default	Description
name	string	required	—	User's full name. Initials are derived as first 2 characters. Background color is deterministic: COLORS[name.charCodeAt(0) % 9].
size	string	optional	'md'	'xs'(24px) \| 'sm'(32px) \| 'md'(40px) \| 'lg'(48px) \| 'xl'(64px) \| '2xl'(80px)
status	string	optional	undefined	Status indicator dot. 'online' \| 'busy' \| 'offline'
shape	string	optional	'circle'	'circle' \| 'square' Square variant used for company/entity avatars.

Design Decisions

Why deterministic background color?

Users expect the same person to always have the same avatar color across all pages and sessions. Deterministic coloring (based on name.charCodeAt(0) % 9) ensures consistency without needing to store a color preference per user. It also ensures the same color is shown in different sessions and browsers.

Changelog

v1.0.0July 2026Added

6 sizes, 9-color deterministic palette, status indicators, group stacking, square variant

States

Default

Circle, initials, dark bg

Online

Green status dot

BSAW+3

Group

Stacked with -8px margin

Accessibility

Requirement	Implementation
alt text	Add aria-label="[Name]'s avatar" on avatar element for screen readers.
Status dot	Announce status change with aria-live region, not just visual dot change.

Composition

Allowed

Table user-cell pattern

Topbar user chip

Avatar groups for team display

Forbidden

Avatar as standalone CTA without button wrapper

More than 5 in a group without +N overflow

Best Practices

Always use deterministic color assignment so the same user always gets the same color.

Consistency builds user recognition across pages and sessions.

Don't

Randomly assign colors on each render.

Random colors confuse users who rely on color for quick identification.

Anatomy

Container

span element. border-radius:50%, display:inline-flex, align-items/justify-content:center. Size set via .avatar-{size} class.

Initials

Text content: first 2 characters of name, uppercase. Color:#fff always. Font-weight:700. Size scales per avatar size.

Background Color

Deterministic: COLORS[name.charCodeAt(0) % 9]. 9 dark tone options. Never changes for same user.

Status Dot (optional)

Absolute positioned span. bottom:0, right:0. 10px circle. border:2px solid #fff. Color: green/red/gray per status.

Content Rules

Good

BS (Budi Santoso)

First 2 chars of full name, uppercase

Bad

B or Budi

Single char or first name only — always use 2 chars from full name

Behavior

Avatars are static display elements with no interactive behavior by default. They render deterministically from the user name — same name always produces same color and initials. If used inside a clickable element (e.g. a user chip in the topbar), the interaction belongs to the parent element, not the avatar. Status dots update reactively when connection state changes — no animation, instant swap.