ProgressBar

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

A visual indicator that communicates how far along a process is. Displays a filled track proportional to the current value, with optional label, helper text, status icon, and icon pair. Supports three sizes and five semantic states including success and error.

When to use

To show progress of a long-running operation — file upload, form completion, onboarding steps, level progression

• When the user needs to understand how much work remains before a task finishes
• When communicating a measurable quantity against a known maximum (e.g. storage used, quiz score, achievement progress)
• When a process has a defined success or failure outcome that should be surfaced inline

When not to use

• For indeterminate loading (duration unknown) — use a Spinner or skeleton instead
• For binary on/off states — use a Toggle or Checkbox
• For navigation between steps
• When the value does not represent progress toward a goal — use a data visualisation chart instead

Content guidelines

Label — describe what is progressing, not the percentage. "Uploading file" not "50% complete". The bar communicates the percentage visually.

Helper text — use a concrete format: "1.2 GB of 5 GB", "Step 3 of 8", "12 seconds remaining". Avoid vague text like "Loading…" if a specific value is available.

Error helper text — be specific about what failed and what the user should do: "Upload failed — file exceeds 50 MB limit", not "Error".

Success helper text — confirm completion positively: "Upload complete", "All steps finished".

Label length — keep the label to a single line. If it wraps, shorten or move to a heading outside the component.

Behaviour guidelines

Value updates — the filled track should animate smoothly when the value changes. Use a CSS transition on width (left-to-right direction). Avoid abrupt jumps except on initial render.

Direction — progress always flows left to right in LTR layouts. Mirror to right-to-left in RTL contexts.

0% state — when value is 0%, the indicator may be invisible or show a minimal visible stub (1–2px) so the user can perceive the track exists. Do not omit the track entirely.

100% vs Success — reaching 100% fill does not automatically trigger the Success state. Switch to Percent=Success only after the process is confirmed complete on the backend. This prevents false positives during the final data transfer window.

Error state — switch to Percent=Error immediately when a failure is detected. The fill level at the point of failure should be preserved — do not reset to 0%. Pair with Helper text explaining the error and an action to recover (e.g. "Retry").

Indeterminate — if the duration is unknown, do not use Progress bar. Use a Spinner or an animated skeleton instead. Do not fake progress by auto-incrementing the bar without real data.

Real-time updates — when progress is driven by a WebSocket or polling interval, throttle UI updates to no more than once every 100–200ms to avoid visual jitter on fast transfers.

Completion transition — after reaching Success, consider keeping the bar visible for 1–2 seconds before replacing it with final content. This gives users time to register the completed state.

Multiple bars — when showing several progress bars simultaneously (e.g. a file upload queue), keep all bars the same size and align them in a vertical list with consistent spacing.

Accessibility

The progress element must use role="progressbar" with aria-valuenow, aria-valuemin="0", and aria-valuemax="100".

Provide aria-label or aria-labelledby pointing to the Label text so screen readers announce what is progressing.

Link the Helper text via aria-describedby so additional context (including error messages) is announced.

Enable Status-icon for terminal states (Success / Error) to communicate state through shape, not colour alone — this satisfies WCAG 1.4.1 (Use of Colour).

For Percent=Error, the error description in Helper text must be programmatically associated with the component so assistive technology surfaces it without the user needing to navigate separately.

When the value updates dynamically, use aria-live="polite" on the helper text region so screen readers announce the change without interrupting current speech.

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.