ProgressBar·component·@astryxdesign/core

Progress Bar

A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.

Open in Playground @astryxdesign/core/ProgressBar

Showcases and examples

5 documented examples

Progress Bar

A progress bar filled to 60%.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · progress-bar-showcase

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {ProgressBar} from '@astryxdesign/core/ProgressBar';

export default function ProgressBarShowcase() {
  return <ProgressBar value={60} label="Progress" style={{width: 300}} />;
}

Usage

Use a determinate bar when the total amount of work is known, and indeterminate when it's not.
Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.
Always provide a label, even if hidden; screen readers need it to announce what's loading.
Place icons or labels inside the bar; compose them alongside it using layout components.
Use a progress bar for instant actions; it's meant for operations that take noticeable time.
Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.

Typed props

Prop	Type and behavior
`label`	`string` · required accessible label
`value`	`number` · default 0 Current value (ignored when indeterminate).
`max`	`number` · default 100 Maximum value.
`isLabelHidden`	`boolean` · default false Visually hide the label (remains accessible).
`hasValueLabel`	`boolean` · default false Show formatted value text (ignored when indeterminate).
`formatValueLabel`	`(value: number, max: number) => string` Custom value label formatter; defaults to a percentage string.
`variant`	`'accent' \| 'success' \| 'warning' \| 'error' \| 'neutral'` · default 'accent' Semantic color variant.
`isIndeterminate`	`boolean` · default false Animated loading indicator for unknown progress.
`marks`	`ReadonlyArray<{value: number; label: string}>` Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them, and take their color from what they sit on: a mark inside the filled area uses the fill variant's on-color (on-accent, on-warning, on-error, and so on), a mark still out on the bare track uses the primary text color (the secondary one on a disabled bar, which dims everything it draws). Each mark requires a label: it is the mark's accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.
`isDisabled`	`boolean` · default false Visually disabled state: grays out the fill and text. Use for canceled or inactive operations.
`xstyle`	`StyleXStyles` StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.

Anatomy

Progress bar · required

Container arranging the label row and progress track.

Label · required

Text naming the operation, optionally hidden visually while remaining accessible.

Value text · optional

Formatted determinate value shown beside the label when requested.

Track · required

Remaining-progress rail that carries the progressbar semantics.

Fill · required

Painted segment showing completed progress or indeterminate movement.

Mark · optional

Labeled target tick positioned on a determinate track.

Theming

Targets

astryx-progress-bar

Visual props: variant

astryx-progress-bar-fill

Visual props: variant

astryx-progress-bar-track

astryx-progress-bar-mark

Visual props: variant, placement

astryx-progressbar

Visual props: variant

Deprecated; use progress-bar.

astryx-progressbar-fill

Visual props: variant

Deprecated; use progress-bar-fill.

astryx-progressbar-track

Deprecated; use progress-bar-track.

astryx-progressbar-mark

Visual props: variant, placement

Deprecated; use progress-bar-mark.

Variables

--_progressbar-mark-width · private

Target mark tick width

Default: 2px

--_progressbar-mark-height · private

Target mark tick height

Default: 8px

Derived properties

width

Uses --_progressbar-mark-width.

Replaces the source property rule.

height

Uses --_progressbar-mark-height.

Replaces the source property rule.