Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Progress

Use to visually represent the completion of a task or process.

Support
Targets (50)

Supported targets

Anchor to ProgressPropsProgressProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or label supplied won't be announced to screen readers.

Anchor to id
id
string

A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

Anchor to max
max
number
Default: 1

The total amount of work the task requires. Must be a value greater than 0 and a valid floating point number.

Learn more about the max attribute.

Anchor to tone
tone
'auto' | 'critical'
Default: 'auto'

The semantic meaning and color treatment of the progress indicator.

  • auto: Automatically determined based on context.
  • critical: Indicates an urgent or error state requiring immediate attention.
Anchor to value
value
number

How much of the task has been completed. Must be a valid floating point number between 0 and max, or between 0 and 1 if max is omitted. When no value is set, the progress bar is indeterminate, indicating an ongoing activity with no estimated completion time.

Learn more about the value attribute.

Anchor to ExamplesExamples

Anchor to Indeterminate stateIndeterminate state

Indeterminate state

Example

Indeterminate state

import {
reactExtension,
Progress,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Progress accessibilityLabel="Loading" />
);
}
import {extension, Progress} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const baseProgress = root.createComponent(Progress, {
accessibilityLabel: 'Loading',
});

root.appendChild(baseProgress);
});

Anchor to Determinate stateDeterminate state

In a determinate state, TextBlock or Text components can be used to communicate what the progress bar is tracking, and to set clear expectations about the current progress.

Determinate state

A determinate progress bar showing progress toward a goal with point counts and a description.

Determinate state

import {
reactExtension,
BlockStack,
Grid,
Progress,
Text,
TextBlock,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.footer.render-after',
() => <Extension />,
);

function Extension() {
const label = 'Queue process';
return (
<BlockStack>
<Grid columns={['fill', 'auto']}>
<Text>{label}</Text>
<Text appearance="subdued">
45% completed
</Text>
</Grid>
<Progress
value={45}
max={100}
accessibilityLabel={label}
/>
<TextBlock appearance="subdued">
Estimated wait time: 4 minutes
</TextBlock>
</BlockStack>
);
}
import {
extension,
BlockStack,
Grid,
Progress,
Text,
TextBlock,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const label = 'Queue process';

const progress = root.createComponent(
BlockStack,
null,
[
root.createComponent(
Grid,
{
columns: ['fill', 'auto'],
},
[
root.createComponent(
Text,
null,
label,
),
root.createComponent(
Text,
{
appearance: 'subdued',
},
'45% completed',
),
],
),
root.createComponent(Progress, {
value: 45,
max: 100,
accessibilityLabel: label,
}),
root.createComponent(
TextBlock,
{
appearance: 'subdued',
},
'Estimated wait time: 4 minutes',
),
],
);

root.appendChild(progress);
},
);

Anchor to Best practicesBest practices

Use components like TextBlock or Text, along with the Progress component, to display text indicating the status of the progress bar.

Anchor to Loading statesLoading states

For loading states, add text to reassure the buyer that the progress bar is not frozen.

A progress bar with 'Loading' text

Anchor to Error statesError states

For error states, add text or a Banner to describe the error and next steps. Use the critical tone property to convey urgency.

A progress bar with error text that says 'There was a problem with the file upload. Please try again.'

Anchor to Visualize a goalVisualize a goal

Use the Progress component to visualize a goal that's valuable to the buyer.

Here's an example of using a progress bar to show a buyer's progress toward the next rewards tier:

A progress bar showing that the buyer is on their way to reaching the next rewards tier.

Here's an example of using a progress bar to show how much more a buyer needs to spend to get free shipping:

A progress bar at checkout, showing that the buyer is $43 away from free shipping.

Anchor to RelatedRelated

ComponentSpinner
Was this page helpful?