Progress

Import

import { Progress } from '@envsemble/envui';

Usage

Progress takes value, how much of the task is done, between min, 0 by default, and max, 100 by default, such as 40 of 100. Its label, above the bar, names it. valueText shows the value at the end of the label's row, formatted by the application; without it, no value shows. aria-valuetext is the value as assistive technology reads it, such as 120 of 480 contacts; without it, the value is read as a percentage of the range.

UploadingFile.tsx

import { Progress } from '@envsemble/envui';

export default function UploadingFile() {
  return (
    <Progress
      label="Uploading quarterly-report.pdf"
      value={40}
      valueText="40%"
      style={{ inlineSize: 'min(100%, 22rem)' }}
    />
  );
}

Amount unknown

value={null} shows an indeterminate bar, which sweeps toward the end of the line, also in right-to-left text, and is read as Loading. Under reduced motion it stands still as faint stripes across the whole track, which no amount reads as. Start with null, set the value once it is known, and replace the bar with the result.

<Progress
  label={preparing ? 'Preparing export' : 'Exporting members'}
  value={preparing ? null : percent}
  valueText={preparing ? undefined : `${percent}%`}
/>

Steps

segments splits the track into that many equal steps, such as 4 for a task of four stages, each filling in turn.

<Progress label="Setting up the workspace" value={2} max={4} segments={4} valueText="Step 2 of 4" />

Composition

The parts are the bar, env-progress, its label, env-progress-label, its value, env-progress-value, the track, env-progress-track, and the indicator, env-progress-indicator; with segments, the track holds one env-progress-segment per step. className, style, ref and data attributes reach the root. Changes of the value aren't announced, so say in a status when the task ends or fails. A TopBar's loading shows a page's progress.

Accessibility

You provide

aria-valuetext where the value isn't a percentage, such as 120 of 480 contacts.
A status that says when the task ends or fails, since changes of the value aren't announced.

envUI provides

role="progressbar" named by label, with its value and range, and no value while unknown.
aria-valuetext from the prop.
No growing or sweeping under reduced motion.

Props

How much of a task is done, such as an upload or an import: a label, an optional value and a bar, exposed as a progress bar. Pass value null while the amount of work is unknown, and the bar sweeps instead.

Prop	Type	Description
`value`required	`numbernull`	How much of the task is done, between min and max, such as 40 of 100; null while the amount of work is unknown, which shows an indeterminate bar announced as Loading.
`segments`	`number`	Splits the track into this many equal steps, such as 4 for a task of four stages, each filling in turn. Without it, the track is one bar.
`label`required	`ReactNode`	What the bar shows, such as Seats assigned; it is visible above the bar and names it.
`min`Default `0`	`number`	The low end of the range.
`max`Default `100`	`number`	The high end of the range.
`valueText`	`ReactNode`	The value as text at the end of the label's row, formatted by the application, such as 2 of 5 or 40%. Without it, no value shows.
`aria-valuetext`	`string`	The value as assistive technology reads it, with its unit in words, such as 2 of 5 seats. Without it, a screen reader reads the value as a percentage of the range, in the locale of the nearest EnvUIProvider.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-progress: The progress bar.
env-progress-header: The row with the label and the value.
env-progress-indicator: The filled part of the track.
env-progress-label: The label.
env-progress-segment: One segment of a segmented bar.
env-progress-track: The track.
env-progress-value: The value as text.
data-indeterminate: Any value, or present
data-segmented: Present

Changelog

1.0.0: The classes are env-progress*; segments splits the track into steps; an indeterminate bar is read as Loading, and sweeps toward the end of the line also in right-to-left text; without aria-valuetext the formatted value stays; className, style, ref and data attributes reach the root.

LoadingBar is no longer exported: TopBar's loading and loadingLabel show page progress, and Progress shows a task's.
1.0.0-prerelease.6: An indeterminate bar sweeps at an even pace, so it enters the track as it leaves and the track never sits empty; the period is the same.

An indeterminate bar sweeps in five times --env-motion-duration-slow, as fast as before, so durations of 0s stop it.

The track and the segments are the neutral fill a Slider's track takes, so empty steps show on dark panels.

Under reduced motion an indeterminate bar shows faint stripes across the whole track, rather than a still bar partway along that read as a value.