Status

A cross-platform React status indicator that pairs a coloured dot with an optional inline label.

Use to visually and textually label of transactions, purchases, etc.

When to use

When you need to communicate the state or outcome of an item (transaction, payment, order, account, system health)

When a compact, color-coded indicator helps users quickly assess status in tables, lists, cards, or detail views

When the state maps to one of the defined palettes — Success, Warning, Alert, Neutral, or Default

When not to use

When the element should trigger an action on click — use a Button or interactive Chip instead

• When you need to show a count or quantity — use a Badge or counter instead
• When the element represents a removable selection or filter — use a Tag instead
• When the meaning requires more than a short label — use regular descriptive text instead

Content guidelines

Keep labels short — one or two words — and use the same vocabulary for the same state across the whole product.

Map each palette to a consistent meaning: Success for positive or completed states, Warning for states needing attention, Alert for failures or critical states, Neutral for inactive or muted states, and Default for a generic state.

Do not invent new color meanings or reuse a palette for an unrelated state.

Never let color carry the meaning by itself — always keep the text label, or, for the dot-only variant, provide an equivalent accessible name.

Use consistent casing for labels across all sizes and palettes.

Behaviour guidelines

Status is display-only — it presents state and does not respond to clicks or hold interactive behavior.

Label: true shows the dot (or colored text) together with its label; Label: false shows the dot only, so use it only where context already makes the meaning obvious.

Label type — Primary colors the text itself in the palette color, while Dot color keeps the text neutral and carries the meaning through a colored dot; pick one approach and apply it consistently within a view.

Size — M [16], L [18], and S [14] scale the text and dot together; match the size to the surrounding content density.

Keep the palette set consistent within a single screen so the same color always means the same thing.

Accessibility

Never rely on color alone to convey state — always pair it with text or an equivalent text alternative.

The dot-only variant (Label: false) must expose its meaning through an accessible label or tooltip, not just the dot color.

Ensure the text and dot meet contrast requirements against their background across every palette.

Use consistent, descriptive wording so the state is unambiguous when announced by a screen reader.

As a non-interactive element, Status should not be focusable; expose its meaning through its text content or accessible name instead.

Installation

npm install @xsolla/xui-status

Imports

import {
  Status,
  type StatusProps,
  type StatusPalette,
  type StatusSize,
  type StatusLabelType,
} from '@xsolla/xui-status';

Quick start

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function QuickStart() {
  return <Status palette="success">Active</Status>;
}

API Reference

<Status>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | children | ReactNode | — | Optional label text rendered next to the dot. | | palette | "default" \| "success" \| "warning" \| "alert" \| "neutral" | "default" | Colour palette for the dot (and optionally the label). | | size | "sm" \| "md" \| "lg" | "md" | Dot size, gap, and label typography. | | labelType | "primary" \| "dot-color" | "primary" | Label colour mode — primary text colour or matching the dot. | | aria-label | string | auto | Accessible label. Auto-generated from palette and string children when omitted. Required for non-string children or localised strings. | | aria-live | "polite" \| "assertive" \| "off" | — | Live-region behaviour. "assertive" switches the role to alert; "off" removes the live-region role entirely. | | id | string | — | HTML id attribute. | | testID | string | — | Test identifier. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Sizes

| Size | Dot | Gap | Font / line height | | --- | --- | --- | --- | | sm | 4px | 4px | 12px / 16px | | md | 6px | 6px | 14px / 20px | | lg | 8px | 8px | 16px / 24px |

Palettes

| Palette | Use case | | --- | --- | | success | Active, completed, operational. | | warning | Pending, degraded, attention needed. | | alert | Error, failed, critical. | | neutral | Inactive, offline, cancelled. | | default | Generic / disabled state. |

Examples

Palettes

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function StatusPalettes() {
  return (
    <div style={{ display: 'flex', gap: 24 }}>
      <Status palette="success">Active</Status>
      <Status palette="warning">Pending</Status>
      <Status palette="alert">Error</Status>
      <Status palette="neutral">Inactive</Status>
    </div>
  );
}

Dot only

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function DotOnly() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <Status palette="success" aria-label="Online" />
      <Status palette="warning" aria-label="Away" />
      <Status palette="alert" aria-label="Offline" />
    </div>
  );
}

Sizes

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function StatusSizes() {
  return (
    <div style={{ display: 'flex', gap: 24, alignItems: 'center' }}>
      <Status size="sm" palette="success">Small</Status>
      <Status size="md" palette="success">Medium</Status>
      <Status size="lg" palette="success">Large</Status>
    </div>
  );
}

Coloured label

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function ColouredLabel() {
  return (
    <div style={{ display: 'flex', gap: 24 }}>
      <Status palette="success" labelType="primary">Primary label</Status>
      <Status palette="success" labelType="dot-color">Coloured label</Status>
    </div>
  );
}

Live region for dynamic updates

import * as React from 'react';
import { Status } from '@xsolla/xui-status';

export default function LiveStatus() {
  const [palette, setPalette] = React.useState<'success' | 'warning' | 'alert'>('success');
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
      <Status palette={palette} aria-live="polite">
        {palette === 'success' ? 'Connected' : palette === 'warning' ? 'Reconnecting' : 'Disconnected'}
      </Status>
      <button onClick={() => setPalette('warning')}>Reconnect</button>
      <button onClick={() => setPalette('alert')}>Disconnect</button>
      <button onClick={() => setPalette('success')}>Restore</button>
    </div>
  );
}

Accessibility

• Defaults to role="status" (implies aria-live="polite"); aria-live="assertive" switches to role="alert"; aria-live="off" removes the live-region role.
• Auto-generates aria-label from palette + string children. Provide an explicit aria-label for non-string content or localised strings.
• The dot is marked aria-hidden so the label (or generated label) carries the meaning.
• Don't rely on colour alone — keep a textual label when the status is meaningful.