ProgressBar

A cross-platform React linear progress bar with optional label, status icon, helper text, and error state.

Installation

npm install @xsolla/xui-progress-bar

Imports

import { ProgressBar } from "@xsolla/xui-progress-bar";

Quick start

import * as React from "react";
import { ProgressBar } from "@xsolla/xui-progress-bar";

export default function QuickStart() {
  return <ProgressBar percent={60} label="Uploading" />;
}

API Reference

<ProgressBar>

| 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. | | percent | number | 0 | Progress value, clamped to 0..100. | | size | "xl" \| "lg" \| "md" \| "sm" \| "xs" \| "l" \| "m" \| "s" | "m" | Bar height and label/helper typography. Long-form (xl, lg, md, sm, xs) and short-form (l, m, s) values are both accepted. Default "m" is equivalent to long-form "md". | | state | "default" \| "success" \| "error" | "default" | Drives bar colour, status icon, and helper styling. | | label | string | — | Label rendered above the bar. | | showLabel | boolean | true | Toggles the entire label row (label, info icon, status icon). | | showInfoIcon | boolean | false | Adds an info icon next to the label. | | showStatusIcon | boolean | true | Renders the default status icon (Check for success, AlertCircle for error). | | helperText | string | — | Helper text rendered below the bar. | | errorMessage | string | — | Replaces helperText when state === "error". | | labelIcon | ReactNode | — | Icon rendered to the left of the label. | | statusIcon | ReactNode | — | Override for the default status icon. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Examples

States

import * as React from "react";
import { ProgressBar } from "@xsolla/xui-progress-bar";

export default function ProgressStates() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <ProgressBar percent={40} label="Default" />
      <ProgressBar
        percent={100}
        state="success"
        label="Success"
        helperText="Done"
      />
      <ProgressBar
        percent={70}
        state="error"
        label="Failed"
        errorMessage="Network error"
      />
    </div>
  );
}

Sizes

import * as React from "react";
import { ProgressBar } from "@xsolla/xui-progress-bar";

export default function ProgressSizes() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
      <ProgressBar percent={50} size="xs" />
      <ProgressBar percent={50} size="sm" />
      <ProgressBar percent={50} size="md" />
      <ProgressBar percent={50} size="lg" />
      <ProgressBar percent={50} size="xl" />
    </div>
  );
}

With helper text and info icon

import * as React from "react";
import { ProgressBar } from "@xsolla/xui-progress-bar";

export default function ProgressHelpers() {
  return (
    <ProgressBar
      percent={35}
      label="Uploading assets"
      helperText="3 of 8 files complete"
      showInfoIcon
    />
  );
}

Animated

import * as React from "react";
import { ProgressBar } from "@xsolla/xui-progress-bar";

export default function AnimatedProgress() {
  const [percent, setPercent] = React.useState(0);
  React.useEffect(() => {
    const id = setInterval(
      () => setPercent((p) => (p >= 100 ? 0 : p + 10)),
      500
    );
    return () => clearInterval(id);
  }, []);
  return <ProgressBar percent={percent} label={`${percent}%`} />;
}

Accessibility

• The bar has role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax.
• Helper text and error messages are linked via aria-describedby.
• Provide a label to give the bar an accessible name.