RichIcon

A cross-platform React compound component for displaying icons, images, or initials in a styled container with selectable shape and size.

Installation

npm install @xsolla/xui-rich-icon

Imports

import {
  RichIcon,
  type RichIconProps,
  type RichIconIconProps,
  type RichIconTextProps,
  type RichIconVariant,
  type RichIconSize,
} from "@xsolla/xui-rich-icon";

Quick start

import * as React from "react";
import { RichIcon } from "@xsolla/xui-rich-icon";
import { Star } from "@xsolla/xui-icons-base";

export default function QuickStart() {
  return (
    <RichIcon size="md" variant="rounded">
      <RichIcon.Icon>
        <Star size={20} />
      </RichIcon.Icon>
    </RichIcon>
  );
}

API Reference

<RichIcon> (root)

| 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. | | children | ReactNode | — | Required. RichIcon.Icon and/or RichIcon.Text descendants. | | variant | "rounded" \| "circle" \| "square" | "rounded" | Container shape. | | size | "sm" \| "md" \| "lg" \| "xl" | "md" | Container size. |

Inherits BoxProps — additional layout props are spread onto the root Box.

<RichIcon.Icon>

| Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | src | string | — | Image URL rendered as a background image. | | component | ReactNode | — | Custom node (e.g. a Lucide icon) when src isn't supplied. | | children | ReactNode | — | Falls back when neither src nor component is set. | | color | string | — | Forwarded to the inner Box via spread, but not applied to the icon child — wrap the icon in your own coloured wrapper if you need to recolour it. |

Inherits BoxProps and ThemeOverrideProps (themeMode, themeProductContext).

<RichIcon.Text>

| Prop | Type | Default | Description | | ---------- | ----------- | ------- | ------------------------------------------------ | | children | ReactNode | — | Required. Text content (typically initials). |

Inherits TextProps and ThemeOverrideProps. Font size is driven by the parent RichIcon's size (10/12/14/18 for sm/md/lg/xl).

Sizes and shapes

| Size | Container | | ---- | --------- | | sm | 24×24 | | md | 32×32 | | lg | 40×40 | | xl | 64×64 |

| Variant | Border radius | | --------- | ------------- | | square | 0 | | rounded | 8 | | circle | 1000 |

Examples

Variants

import * as React from "react";
import { RichIcon } from "@xsolla/xui-rich-icon";
import { User } from "@xsolla/xui-icons-base";

export default function Variants() {
  return (
    <div style={{ display: "flex", gap: 16 }}>
      <RichIcon size="lg" variant="square">
        <RichIcon.Icon>
          <User size={24} />
        </RichIcon.Icon>
      </RichIcon>
      <RichIcon size="lg" variant="rounded">
        <RichIcon.Icon>
          <User size={24} />
        </RichIcon.Icon>
      </RichIcon>
      <RichIcon size="lg" variant="circle">
        <RichIcon.Icon>
          <User size={24} />
        </RichIcon.Icon>
      </RichIcon>
    </div>
  );
}

Initials

import * as React from "react";
import { RichIcon } from "@xsolla/xui-rich-icon";

export default function Initials() {
  const users = [
    { name: "John Doe", initials: "JD" },
    { name: "Alice Smith", initials: "AS" },
  ];
  return (
    <div style={{ display: "flex", gap: 8 }}>
      {users.map(({ name, initials }) => (
        <RichIcon key={name} size="md" variant="circle" aria-label={name}>
          <RichIcon.Text>{initials}</RichIcon.Text>
        </RichIcon>
      ))}
    </div>
  );
}

Image

import * as React from "react";
import { RichIcon } from "@xsolla/xui-rich-icon";

export default function ImageExample() {
  return (
    <RichIcon size="lg" variant="circle" aria-label="Profile">
      <RichIcon.Icon src="https://example.com/avatar.jpg" />
    </RichIcon>
  );
}

Accessibility

• The root container is decorative by default — pass aria-label for meaningful icons.
• Text children rendered via RichIcon.Text are accessible to screen readers.
• Ensure sufficient contrast between text and the container background.