Avatar

A cross-platform React avatar component that displays user images, icons, or text initials. Supports badges for notifications and can be grouped together.

Installation

npm install @xsolla/xui-avatar
# or
yarn add @xsolla/xui-avatar

Demo

Basic Avatar

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function BasicAvatar() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Avatar src="https://example.com/user.jpg" />
      <Avatar text="JD" />
      <Avatar /> {/* Default user icon */}
    </div>
  );
}

Avatar Sizes

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function AvatarSizes() {
  return (
    <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
      <Avatar size="xs" text="XS" />
      <Avatar size="sm" text="S" />
      <Avatar size="md" text="M" />
      <Avatar size="lg" text="L" />
      <Avatar size="xl" text="XL" />
    </div>
  );
}

Avatar with Badge

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function AvatarWithBadge() {
  return (
    <div style={{ display: 'flex', gap: 24 }}>
      <Avatar src="https://example.com/user.jpg" badge />
      <Avatar src="https://example.com/user.jpg" badge badgeCount={5} />
      <Avatar src="https://example.com/user.jpg" badge badgeCount={99} badgeTone="alert" />
    </div>
  );
}

Square Avatar

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function SquareAvatar() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Avatar src="https://example.com/user.jpg" />
      <Avatar src="https://example.com/user.jpg" square />
    </div>
  );
}

Anatomy

Import the component and use it directly:

import { Avatar } from '@xsolla/xui-avatar';

<Avatar
  src="image-url"            // Image source URL
  text="AB"                  // Text/initials when no image
  icon={<CustomIcon />}      // Custom icon when no image
  size="md"                   // Size variant
  square={false}             // Square vs circular
  badge={false}              // Show notification badge
  badgeCount={5}             // Badge count
  badgeTone="brand"          // Badge color tone
  stroke={false}             // Show border
  backgroundColor="#color"   // Custom background
  onClick={handleClick}      // Click handler
/>

Examples

Avatar with Custom Icon

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';
import { Building2, Briefcase, Star } from '@xsolla/xui-icons-base';

export default function AvatarWithIcon() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Avatar icon={<Building2 />} backgroundColor="#4A90D9" />
      <Avatar icon={<Briefcase />} backgroundColor="#9B59B6" />
      <Avatar icon={<Star />} backgroundColor="#F39C12" />
    </div>
  );
}

Avatar with Stroke

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function AvatarWithStroke() {
  return (
    <Avatar
      src="https://example.com/user.jpg"
      stroke
      size="lg"
    />
  );
}

Clickable Avatar

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function ClickableAvatar() {
  return (
    <Avatar
      text="JD"
      size="lg"
      onClick={() => alert('Avatar clicked!')}
      aria-label="View John Doe's profile"
    />
  );
}

Avatar Group

import * as React from 'react';
import { AvatarGroup } from '@xsolla/xui-avatar';

export default function AvatarGroupExample() {
  const users = [
    { src: 'https://example.com/user1.jpg' },
    { src: 'https://example.com/user2.jpg' },
    { initials: 'JD' },
    { initials: 'AB' },
    { initials: 'CD' },
    { initials: 'EF' },
    { initials: 'GH' },
  ];

  return (
    <AvatarGroup
      list={users}
      maxVisible={5}
      size="md"
    />
  );
}

Badge Tones

import * as React from 'react';
import { Avatar } from '@xsolla/xui-avatar';

export default function BadgeTones() {
  return (
    <div style={{ display: 'flex', gap: 24 }}>
      <Avatar text="A" badge badgeCount={3} badgeTone="brand" />
      <Avatar text="B" badge badgeCount={3} badgeTone="success" />
      <Avatar text="C" badge badgeCount={3} badgeTone="warning" />
      <Avatar text="D" badge badgeCount={3} badgeTone="alert" />
    </div>
  );
}

API Reference

Avatar

An avatar component for displaying user representation.

Avatar Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | src | string | - | Image source URL. | | icon | ReactNode | - | Icon to display when no image. | | text | string | - | Text/initials when no image or icon. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" | "md" | Size of the avatar. | | square | boolean | false | Square with border radius vs circular. | | badge | boolean | false | Show notification badge. | | badgeCount | ReactNode | - | Badge count or content. | | badgeTone | "primary" \| "secondary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral" | - | Badge color tone. | | stroke | boolean | false | Show border around avatar. | | backgroundColor | string | - | Custom background color. | | disableHover | boolean | false | Disable hover effect. | | aria-label | string | - | Accessible label. | | alt | string | - | Alt text for image. | | onClick | () => void | - | Click handler. |

AvatarGroup

A component for displaying multiple avatars with overlap.

AvatarGroup Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | list | AvatarGroupItem[] | - | Required. Array of avatar items. | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Size of avatars. | | maxVisible | number | 6 | Max avatars before "+N" counter. | | stroke | boolean | true | Show borders on avatars. | | avatarBackgroundMode | "mixed" \| ToneString \| Function | "mixed" | Background color mode. | | aria-label | string | - | Accessible label for the group. |

AvatarGroupItem:

interface AvatarGroupItem {
  src?: string;         // Image URL
  initials?: string;    // Text initials
  onClick?: () => void; // Click handler
  tooltip?: string;     // Tooltip on hover
}

Theming

Avatar uses the design system theme for colors:

// Colors accessed via theme
theme.colors.background.secondary   // Default avatar background
theme.colors.content.primary        // Text/icon color
theme.colors.border.primary         // Stroke color

Accessibility

• Supports aria-label for screen readers
• alt attribute for images
• Keyboard accessible when clickable (Enter/Space)
• Focus indicator follows WCAG guidelines
• Badge count announced to assistive technology