Progress indicator

Progress indicators express the length of in-progress operations.

Usage

There are two types of progress indicators available as separate components:

ProgressLinear: shows progress on a linear bar.
ProgressRadial: shows progress in a circular form.

import * as React from 'react';
import { ProgressLinear, ProgressRadial } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressLinear />
      <ProgressRadial />
    </div>
  );
};

By default, the progress indicators are considered to be “indeterminate”. This is useful for short processes, where it isn’t necessary (or possible) to indicate the completion percentage. For longer processes, a “determinate” progress indicator should be used.

Value

To specify a value for determinate progress indicator, the value prop can be used. This prop is available for both ProgressLinear and ProgressRadial. The value must be inclusively between 0 and 100, representing what percentage of the task has been completed.

import * as React from 'react';
import { ProgressLinear, ProgressRadial } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressLinear value={20} />
      <ProgressRadial value={50} />
    </div>
  );
};

Exclusively for ProgressLinear, the isAnimated flag is helpful when applying animation to the indicator as the value changes.

import * as React from 'react';
import { Button, ProgressLinear } from '@itwin/itwinui-react';

export default () => {
  const [value, setValue] = React.useState(0);
  const isDone = value === 100;

  React.useEffect(() => {
    let interval;

    if (!isDone) {
      interval = setInterval(
        () => setValue((prevValue) => prevValue + 20),
        1500,
      );
    }

    return () => clearInterval(interval);
  }, [isDone]);

  return (
    <div className='demo-container'>
      <ProgressLinear
        value={value}
        isAnimated={!isDone}
        labels={!isDone ? ['Loading...', `${value}%`] : ['Upload succeeded.']}
        status={isDone ? 'positive' : undefined}
        key={isDone.toString()}
      />
      <Button onClick={() => setValue(0)}>Reset process</Button>
    </div>
  );
};

Note: If the indeterminate prop is set to true, this value will be ignored.

Status

The status prop can be used to convey the outcome of a process. The recommended UX flow is to display the default progress indicator during the loading process, and then update the status to reflect whether the process was successful, encountered an error, or requires attention.

Three available statuses are:

"positive": to indicate success.
"negative": to indicate failure.
"warning": to indicate a cautionary state or partial success.

import * as React from 'react';
import { ProgressLinear } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressLinear
        value={100}
        labels={['Upload succeeded!']}
        status='positive'
      />
      <ProgressLinear
        value={50}
        labels={['Upload failed.', '50%']}
        status='negative'
      />
      <ProgressLinear
        value={75}
        labels={['Attention required.', '75%']}
        status='warning'
      />
    </div>
  );
};

When using the status prop, each ProgressRadial is accompanied by a status icon, which provides a visual cue to inform the current progress state better. The status icon can also be replaced by custom content for more advanced uses.

import * as React from 'react';
import { ProgressRadial } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressRadial value={100} status='positive' />
      <ProgressRadial value={50} status='negative' />
      <ProgressRadial value={75} status='warning' />
    </div>
  );
};

Label

Indicator labels can be passed into the labels prop as an array. If one label is passed, it will be centered. If there are two labels, each is pushed to one end of the progress indicator. This prop is only available for ProgressLinear.

import * as React from 'react';
import { ProgressLinear } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressLinear value={50} labels={['Centered Label']} />
      <ProgressLinear value={50} labels={['Loading...', '50%']} />
    </div>
  );
};

Size

Four size options available are:

"x-small"
"small"
"medium" (default)
"large"

This prop is only available for ProgressRadial.

import * as React from 'react';
import { ProgressRadial } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ProgressRadial size='x-small' />
      <ProgressRadial size='small' />
      <ProgressRadial />
      <ProgressRadial size='large' />
    </div>
  );
};

Content

The ProgressRadial component can be wrapped around JSX elements, such as icons or texts. This content helps provide flexibility to enhance the progress display with additional visual appearance. This prop is only available for ProgressRadial.

import * as React from 'react';
import { ProgressRadial, Text } from '@itwin/itwinui-react';

export default () => {
  return (
    <ProgressRadial value={100} status='positive' size='large'>
      <Text variant='small'>100%</Text>
    </ProgressRadial>
  );
};

Note: Indicators of "x-small" size will not display its content.

Accessibility

To make the progress indicator accessible to non-sighted users, a visually-hidden “Loading” message will be automatically included when the value is not set to 100%.

To further improve the experience, applications should have a mechanism to inform users once the loading process is complete. Depending on the criticality of the content and how long it takes to load, the progress completion can be indicated using a live region, or by programmatically moving focus to the top of the new content.

Props

ProgressLinear

Prop	Description	Default
value	Progress percentage. Should be a number between 0 and 100. number
indeterminate	Progress variant. If true, `value` will be ignored. Defaults to true if `value` is passed, otherwise false. boolean
labels	Labels array. One label will be centered, two will be put to the sides. ReactNode[]
isAnimated	Apply animation to the value change, if determinate. boolean	false
status	Status of progress. "positive" \| "negative" \| "warning"
labelGroupProps	Pass props to ProgressLinear label group. DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>

ProgressRadial

Prop	Description	Default
value	Progress percentage. Should be a number between 0 and 100. number
indeterminate	Progress variant. If true, value will be ignored. boolean	false if value is provided, true otherwise
status	Status of Progress. Positive status always has 100% value. "positive" \| "negative" \| "warning"
size	Size of the progress indicator. Defaults to medium size. "" \| "small" \| "x-small" \| "large"	''
children	Content shown inside progress indicator. ReactNode
as	"symbol" \| "object" \| "div" \| "a" \| "abbr" \| "address" \| "area" \| "article" \| "aside" \| "audio" \| "b" \| "base" \| "bdi" \| "bdo" \| "big" \| "blockquote" \| "body" \| "br" \| "button" \| "canvas" \| ... 158 more ... \| FunctionComponent<...>