IconWrapper

A cross-platform container that gives icons, labels, images, and avatars a consistent box, alignment, and shape. It resolves its dimensions and default background from the active theme.

This is a universal container component used to display small visual elements in a consistent and scalable way. It ensures uniform sizing, alignment, and shapes across different types of content.

Installation

npm install @xsolla/xui-icon-wrapper

Imports

import { IconWrapper, type IconWrapperProps } from "@xsolla/xui-icon-wrapper";

Quick start

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

export default function QuickStart() {
  return (
    <IconWrapper size="md" shape="smooth">
      <Star size="100%" aria-hidden />
    </IconWrapper>
  );
}

API Reference

<IconWrapper>

| 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 | — | Element rendered inside the wrapper. | | size | "xxs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Wrapper size. Resolved against theme.sizing.iconWrapper. | | shape | "none" \| "smooth" \| "full" | "none" | Border-radius style. "smooth" rounds to ~size/6 (min 4px); "full" is fully circular. | | type | "icon" \| "label" \| "image" \| "avatar" \| "brand" \| "custom" | — | Hint describing the wrapped content. Reserved for future styling rules; currently has no visual effect. | | backgroundColor | string | theme default (transparent for shape="none") | Background colour override. | | borderColor | string | — | Border colour. When set, a 1px border is drawn. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Examples

Sizes

import * as React from "react";
import { IconWrapper } from "@xsolla/xui-icon-wrapper";
import { Heart } from "@xsolla/xui-icons-base";

export default function Sizes() {
  return (
    <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
      <IconWrapper size="xxs">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper size="xs">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper size="sm">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper size="md">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper size="lg">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper size="xl">
        <Heart size="100%" aria-hidden />
      </IconWrapper>
    </div>
  );
}

Shapes

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

export default function Shapes() {
  return (
    <div style={{ display: "flex", gap: 16, alignItems: "center" }}>
      <IconWrapper shape="none" size="lg">
        <User size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper shape="smooth" size="lg">
        <User size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper shape="full" size="lg">
        <User size="100%" aria-hidden />
      </IconWrapper>
    </div>
  );
}

Status badges

import * as React from "react";
import { IconWrapper } from "@xsolla/xui-icon-wrapper";
import { Check, Warning, RemoveCr } from "@xsolla/xui-icons-base";

export default function StatusBadges() {
  return (
    <div style={{ display: "flex", gap: 16 }}>
      <IconWrapper shape="full" size="md" backgroundColor="#4CAF50">
        <Check color="#fff" size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper shape="full" size="md" backgroundColor="#FF9800">
        <Warning color="#fff" size="100%" aria-hidden />
      </IconWrapper>
      <IconWrapper shape="full" size="md" backgroundColor="#F44336">
        <RemoveCr color="#fff" size="100%" aria-hidden />
      </IconWrapper>
    </div>
  );
}

Brand icon container

import * as React from "react";
import { IconWrapper } from "@xsolla/xui-icon-wrapper";
import { Github, Discord, Twitch } from "@xsolla/xui-icons-brand";

export default function BrandTiles() {
  return (
    <div style={{ display: "flex", gap: 12 }}>
      <IconWrapper size="lg" shape="smooth">
        <Github size={24} aria-hidden />
      </IconWrapper>
      <IconWrapper size="lg" shape="smooth">
        <Discord size={24} aria-hidden />
      </IconWrapper>
      <IconWrapper size="lg" shape="smooth">
        <Twitch size={24} aria-hidden />
      </IconWrapper>
    </div>
  );
}

Accessibility

• The wrapper is a presentational container — it does not add any ARIA attributes.
• Set aria-label on interactive children, or aria-hidden on decorative icons.
• For interactive icon-only controls, use IconButton from @xsolla/xui-button rather than wrapping a click handler around IconWrapper.