Avatar

A cross-platform React avatar component that displays a user image, icon, or text initials. Supports notification badges and grouping via AvatarGroup.

Installation

npm install @xsolla/xui-avatar

Imports

import {
  Avatar,
  AvatarGroup,
  type AvatarGroupItem,
  type AvatarBackgroundMode,
} from "@xsolla/xui-avatar";

Quick start

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

export default function QuickStart() {
  return <Avatar text="JD" aria-label="John Doe" />;
}

API Reference

<Avatar>

| Prop | Type | Default | Description | | ------------ | ------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | src | string | — | Image source URL. | | icon | ReactNode | — | Icon displayed when no src is supplied. | | text | string | — | Text/initials displayed when no src or icon is supplied. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" \| "xxs" | "xl" | Avatar size. | | square | boolean | false | Square (small radius) instead of circular. | | tone | "mono" \| "brand" | "mono" | Visual tone. | | badge | boolean | false | Show a notification badge. | | badgeCount | ReactNode | — | Numeric or text content rendered inside the badge. | | badgeIcon | ReactNode | — | Icon rendered inside the badge. | | badgeTone | "primary" \| "secondary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral" | "alert" | Badge colour tone. | | aria-label | string | — | Accessible label. Recommended for screen readers. | | alt | string | — | Alt text for the image (falls back to aria-label). | | onClick | () => void | — | Click handler. When provided, the avatar becomes a focusable button. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

backgroundColor and disableHover exist on the source type but are reserved for internal use by AvatarGroup (@internal); avoid setting them directly.

<AvatarGroup>

| Prop | Type | Default | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------- | | list | AvatarGroupItem[] | — | Required. Avatars to display. | | size | "xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" | "sm" | Size applied to every avatar. | | maxVisible | number | 6 | Maximum slots rendered, including the "+N" overflow counter. | | avatarBackgroundMode | "mixed" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral" \| ((theme) => string) | "mixed" | Background colour mode for non-image avatars. | | aria-label | string | auto | Accessible label for the group. Defaults to "X users" / "N of M users". |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

AvatarGroupItem

interface AvatarGroupItem {
  src?: string;
  initials?: string;
  tooltip?: string;
  badge?: boolean;
  badgeCount?: React.ReactNode;
  badgeIcon?: React.ReactNode;
  badgeTone?: AvatarProps["badgeTone"];
}

Examples

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="xxs" text="A" />
      <Avatar size="xs" text="A" />
      <Avatar size="sm" text="A" />
      <Avatar size="md" text="A" />
      <Avatar size="lg" text="A" />
      <Avatar size="xl" text="A" />
    </div>
  );
}

Tones

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

export default function AvatarTones() {
  return (
    <div style={{ display: "flex", gap: 16 }}>
      <Avatar tone="mono" text="JD" />
      <Avatar tone="brand" text="JD" />
    </div>
  );
}

With badge

import * as React from "react";
import { Avatar } from "@xsolla/xui-avatar";
import { Bell } from "@xsolla/xui-icons-base";

export default function AvatarWithBadge() {
  return (
    <div style={{ display: "flex", gap: 24 }}>
      <Avatar text="JD" badge />
      <Avatar text="JD" badge badgeCount={5} />
      <Avatar text="JD" badge badgeIcon={<Bell />} badgeTone="brand" />
    </div>
  );
}

Square

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

export default function SquareAvatar() {
  return <Avatar text="AB" square size="lg" />;
}

Custom icon

import * as React from "react";
import { Avatar } from "@xsolla/xui-avatar";
import { Briefcase } from "@xsolla/xui-icons-base";

export default function AvatarWithIcon() {
  return <Avatar icon={<Briefcase />} tone="brand" aria-label="Work account" />;
}

Clickable

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

export default function ClickableAvatar() {
  const [count, setCount] = React.useState(0);
  return (
    <Avatar
      text="JD"
      size="lg"
      onClick={() => setCount((c) => c + 1)}
      aria-label={`Open profile (clicked ${count} times)`}
    />
  );
}

Avatar group

import * as React from "react";
import { AvatarGroup, type AvatarGroupItem } from "@xsolla/xui-avatar";

export default function AvatarGroupExample() {
  const users: AvatarGroupItem[] = [
    { initials: "JD", tooltip: "John Doe" },
    { initials: "AB", tooltip: "Anna Brown" },
    { initials: "CD", tooltip: "Carl Davis" },
    { initials: "EF", tooltip: "Emma Frost" },
    { initials: "GH", tooltip: "Grace Hill" },
    { initials: "IJ", tooltip: "Ivan Jones" },
    { initials: "KL", tooltip: "Kim Lee" },
  ];

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

Accessibility

• Pass aria-label so screen readers can identify the avatar; alt falls back to it for images.
• When onClick is set the root receives role="button", tabIndex={0}, and Enter/Space activation.
• AvatarGroup is a role="group" with an auto-generated label such as "5 of 12 users".
• The "+N" overflow counter announces "N more user(s)" via aria-label.