LinearProgress

Horizontal progress bar with optional label, buffer, segmented stacks, and indeterminate loading.

stable
since v0.1.0
2.4 kB
data-display
progress
feedback

Preview

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '20rem' }}>
      <LinearProgress value={60} />
    </div>
  );
}

Usage

import { LinearProgress } from '@arshad-shah/cynosure-react';

<LinearProgress value={60} />

For custom layouts, compose with LinearProgressRoot, LinearProgressTrack, LinearProgressIndicator, LinearProgressBuffer, LinearProgressSegment, LinearProgressHeader, LinearProgressLabel, LinearProgressMeta, and LinearProgressValue directly.

Sizes

Four sizes are available: xs, sm, md (default), and lg.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '20rem', display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
      <LinearProgress value={60} size="xs" />
      <LinearProgress value={60} size="sm" />
      <LinearProgress value={60} size="md" />
      <LinearProgress value={60} size="lg" />
    </div>
  );
}

Color schemes

Pick a scheme that matches the surrounding context: accent, success, warning, danger, or neutral.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '20rem', display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
      <LinearProgress value={60} colorScheme="accent" />
      <LinearProgress value={60} colorScheme="success" />
      <LinearProgress value={60} colorScheme="warning" />
      <LinearProgress value={60} colorScheme="danger" />
      <LinearProgress value={60} colorScheme="neutral" />
    </div>
  );
}

With label

Pass label and meta for a two-up header above the bar. Set showValue to render the formatted percentage below.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '22rem' }}>
      <LinearProgress
        value={64}
        label="Uploading project assets"
        meta="2.4 MB / 3.8 MB"
        showValue
      />
    </div>
  );
}

Indeterminate

Pass indeterminate for an unknown-duration loader. The ARIA value attributes are dropped so assistive tech announces an unspecified loading state.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '22rem' }}>
      <LinearProgress indeterminate label="Loading" aria-label="Loading" />
    </div>
  );
}

Buffer

Pass buffer for a YouTube-style preloaded zone behind the active indicator.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '22rem' }}>
      <LinearProgress value={32} buffer={68} label="Streaming" meta="1:48 / 5:32" />
    </div>
  );
}

Segments

Pass a segments array for a stacked multi-value bar — each segment becomes a LinearProgressSegment with its own colour scheme.

Preview

Open

tsx

import { LinearProgress } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <div style={{ width: '22rem' }}>
      <LinearProgress
        max={100}
        label="Storage"
        meta="78 GB of 100 GB"
        segments={[
          { value: 48, colorScheme: 'accent', label: 'Photos' },
          { value: 20, colorScheme: 'success', label: 'Documents' },
          { value: 10, colorScheme: 'warning', label: 'Other' },
        ]}
      />
    </div>
  );
}

API

PropTypeDefaultDescription

value

number

Current progress value. Ignored when `indeterminate` or `segments` is set.

max

number

100

Upper bound used to compute the filled percentage.

size

"xs"|"sm"|"md"|"lg"

Height/font preset for the bar.

colorScheme

"accent"|"success"|"warning"|"danger"|"neutral"

accent

Colour role for the filled portion.

variant

"solid"|"ticked"

solid

Visual treatment: `solid` (flat colour) or `striped` (animated stripes).

indeterminate

boolean

false

Render the indeterminate loop animation instead of a value-driven fill.

buffer

number

—

YouTube-style preloaded / reserved progress bar behind the indicator.

segments

LinearProgressSegmentDescriptor[]

—

Stacked multi-value bar — mutually exclusive with plain `value`. Each entry becomes a `<LinearProgressSegment>`.

showValue

boolean

false

Render the formatted value below the track.

label

ReactNode

—

Short label rendered above the track (left side).

Accessibility

Renders role="progressbar" on the root with aria-valuenow, aria-valuemin, and aria-valuemax.
aria-valuetext follows formatValue (defaults to "NN%") so screen readers announce a human-readable value.
Omits the value when indeterminate is set so assistive tech reports “loading” instead.
When label is a string it doubles as the accessible name; otherwise pass an explicit aria-label.
data-complete flips on once value >= max (unless completionState="none"), letting you style the finished state without extra state.

Recipes

Use variant="ticked" for a stepped bar that emphasises discrete progress milestones.
Pass a formatValue callback like (v, max) => `${v} of ${max}` to switch from a percent readout to a count.
Use segments to visualise quota usage (e.g. used / reserved / free) in a single bar.
Combine buffer + value to surface “downloaded” vs “playing back” progress for media players.