Badge

A cross-platform React badge component for counts, status dots, and small labels. Sizes xs and sm render as content-less dots; larger sizes accept text and icons.

Use it with numbers or text inside for show notifications, counts, or status information on navigation items and icons.

You can change colors in accordance with the Color mapping table to use it inside other components and patterns.

Installation

npm install @xsolla/xui-badge

Imports

import { Badge } from "@xsolla/xui-badge";

Quick start

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function QuickStart() {
  return <Badge tone="alert">5</Badge>;
}

API Reference

<Badge>

| 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 | — | Badge content. Numeric values greater than 999 are clamped to 999+. Ignored for xs/sm sizes. | | icon | ReactNode | — | Icon rendered alongside content. Ignored for xs/sm sizes. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" | "md" | Badge size. xs and sm are dot-only. | | tone | "primary" \| "secondary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral" | "alert" | Colour tone. | | square | boolean | false | Use a small square radius (4px) instead of pill/circle. | | showStroke | boolean | false | Render a 1px border in the page background colour, useful when overlaid on imagery. | | aria-label | string | — | Accessible label. | | aria-hidden | boolean | auto | Defaults to true for content-less dots without aria-label. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Examples

Tones

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function BadgeTones() {
  return (
    <div style={{ display: "flex", gap: 16 }}>
      <Badge tone="primary">P</Badge>
      <Badge tone="secondary">S</Badge>
      <Badge tone="brand">B</Badge>
      <Badge tone="brandExtra">X</Badge>
      <Badge tone="success">9</Badge>
      <Badge tone="warning">!</Badge>
      <Badge tone="alert">3</Badge>
      <Badge tone="neutral">N</Badge>
    </div>
  );
}

Sizes

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function BadgeSizes() {
  return (
    <div style={{ display: "flex", gap: 16, alignItems: "center" }}>
      <Badge size="xs" tone="alert" aria-label="Unread" />
      <Badge size="sm" tone="alert" aria-label="Unread" />
      <Badge size="md" tone="alert">
        5
      </Badge>
      <Badge size="lg" tone="alert">
        5
      </Badge>
      <Badge size="xl" tone="alert">
        5
      </Badge>
    </div>
  );
}

With icon

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";
import { Heart } from "@xsolla/xui-icons-base";

export default function BadgeWithIcon() {
  return (
    <Badge tone="warning" icon={<Heart />}>
      Featured
    </Badge>
  );
}

Square

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function SquareBadge() {
  return (
    <Badge tone="brand" square>
      NEW
    </Badge>
  );
}

Notification count

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function NotificationCount() {
  const [count, setCount] = React.useState(12);
  return (
    <button
      onClick={() => setCount((c) => c + 1)}
      style={{ position: "relative" }}
    >
      Inbox
      <span style={{ position: "absolute", top: -8, right: -8 }}>
        <Badge tone="alert">{count}</Badge>
      </span>
    </button>
  );
}

With stroke

import * as React from "react";
import { Badge } from "@xsolla/xui-badge";

export default function BadgeStroke() {
  return (
    <div style={{ background: "#222", padding: 16 }}>
      <Badge tone="brand" showStroke>
        Pro
      </Badge>
    </div>
  );
}

Accessibility

• The root has role="status" so changes are announced politely.
• Dot-only badges (xs, sm) without an aria-label default to aria-hidden="true".
• Provide aria-label for badges that convey state visually only (such as a coloured dot beside an avatar).