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 the Progress component to visually represent the completion of a task or process. The component supports both determinate (known percentage) and indeterminate (unknown duration) states.

Pair Progress with Text or TextBlock components to communicate what the progress bar is tracking. For a loading indicator without a progress bar, use Spinner instead.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Progress component.

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 Show a loading stateShow a loading state

Use an indeterminate progress bar when the duration of an operation isn't known. Omit the value prop to render an animated loading indicator.

Show a loading state

An indeterminate progress bar with a loading animation.

Show a loading state

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

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

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

export default extension('customer-account.page.render', (root) => {
const baseProgress = root.createComponent(Progress, {
accessibilityLabel: 'Loading',
});

root.appendChild(baseProgress);
});

Anchor to Track progress toward a goalTrack progress toward a goal

Set a value and max to show determinate progress. This example displays a rewards tier progress bar with point counts and a description of how many more points are needed.

Track progress toward a goal

A determinate progress bar showing 350 out of 500 points toward a rewards tier.

Track progress toward a goal

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

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
const label = 'Rewards progress';
return (
<BlockStack>
<Grid columns={['fill', 'auto']}>
<Text>{label}</Text>
<Text appearance="subdued">
350 / 500 points
</Text>
</Grid>
<Progress
value={350}
max={500}
accessibilityLabel={label}
/>
<TextBlock appearance="subdued">
Earn 150 more points to reach Gold tier
</TextBlock>
</BlockStack>
);
}
import {
extension,
BlockStack,
Grid,
Progress,
Text,
TextBlock,
} from '@shopify/ui-extensions/customer-account';

export default extension(
'customer-account.page.render',
(root) => {
const label = 'Rewards progress';

const progress = root.createComponent(
BlockStack,
null,
[
root.createComponent(
Grid,
{columns: ['fill', 'auto']},
[
root.createComponent(Text, null, label),
root.createComponent(
Text,
{appearance: 'subdued'},
'350 / 500 points',
),
],
),
root.createComponent(Progress, {
value: 350,
max: 500,
accessibilityLabel: label,
}),
root.createComponent(
TextBlock,
{appearance: 'subdued'},
'Earn 150 more points to reach Gold tier',
),
],
);

root.appendChild(progress);
},
);

Anchor to Indicate an error stateIndicate an error state

Use the critical tone to visually communicate that a process has failed. Pair the progress bar with a Banner to describe the error and guide the customer toward a resolution.

Indicate an error state

import {
reactExtension,
BlockStack,
Progress,
Banner,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<BlockStack>
<Progress
value={0.3}
tone="critical"
accessibilityLabel="Upload failed"
/>
<Banner
status="critical"
title="The file upload failed. Check your file and try again."
/>
</BlockStack>
);
}
import {
extension,
BlockStack,
Progress,
Banner,
} from '@shopify/ui-extensions/customer-account';

export default extension(
'customer-account.page.render',
(root) => {
const container = root.createComponent(BlockStack, null, [
root.createComponent(Progress, {
value: 0.3,
tone: 'critical',
accessibilityLabel: 'Upload failed',
}),
root.createComponent(Banner, {
status: 'critical',
title:
'The file upload failed. Check your file and try again.',
}),
]);

root.appendChild(container);
},
);

Anchor to Best practicesBest practices

  • Pair with text to communicate status: The progress bar alone doesn't convey what's happening. Add a label, percentage, or description using Text or TextBlock components.
  • Add reassuring text for loading states: When using an indeterminate progress bar, include text like "Loading..." to confirm the operation is still in progress.
  • Use the critical tone with an error description: When a process fails, switch the tone to critical and add a Banner or text describing the error and next steps.
  • Visualize meaningful goals: Use determinate progress bars for goals that are valuable to the customer, like rewards tiers or free shipping thresholds.

Anchor to LimitationsLimitations

  • The Progress component doesn't include a built-in text label. Pair it with Text or TextBlock to describe the current state.
  • The value must be a valid floating point number between 0 and max (or between 0 and 1 if max is omitted).
  • There's no animation control for the indeterminate state. The animation runs automatically when value is omitted.
  • Customers who prefer reduced motion see a static text label instead of the animated indicator, if accessibilityLabel is set.
Was this page helpful?