SProgress <s-progress>

A progress bar that shows how far a task has advanced toward its maximum value. SProgress is the typed Vue 3 wrapper for Shopify's Polaris <s-progress> web component.

import { SProgress } from 'polaris-vue-elements'

Best practices

• Use it for work you can measure. Reach for a progress bar when you can express the work as part of a whole. When you can't tell how long something will take or how far along it is, a spinner is the lighter choice.
• Name what's progressing. Give accessibilityLabel a precise description, for example "Importing products" or "Storage used". Screen readers read the bar out under that label, and there's no default if you leave it off.
• Add text when the numbers matter. The bar shows no label or percentage itself, so put text next to it when merchants need the figures, and keep that text in step with value.
• Set max to the real total. Use the true count or cap, such as how many files there are or how big a quota is, rather than turning it all into a percentage. That makes value simple to update as work finishes.
• Use tone only to signal trouble. Reserve tone="critical" and tone="warning" for progress that points to a problem, such as a limit that's been used up. Leave ordinary in-progress work on the default tone.

<SProgress accessibilityLabel="Importing products" :value="120" :max="300" />
<SText>120 of 300 products imported</SText>

See Shopify's best practices for <s-progress> for the full guidance.

Example

Upload next file (40%)

<script setup>
import { ref } from 'vue'
import { SProgress, SButton } from 'polaris-vue-elements'

const uploaded = ref(40)

function advance() {
  uploaded.value = Math.min(uploaded.value + 20, 100)
}
</script>

<template>
  <!-- determinate: bind numeric props, don't write them as string attributes -->
  <SProgress accessibilityLabel="Import progress" :value="uploaded" :max="100" />

  <!-- toned -->
  <SProgress accessibilityLabel="Sync progress" tone="success" :value="80" :max="100" />

  <!-- indeterminate: omit `value` entirely -->
  <SProgress accessibilityLabel="Preparing export" />

  <SButton @click="advance">Upload next file ({{ uploaded }}%)</SButton>
</template>

Props

Prop	Type	Description
accessibilityLabel	string	A label that describes the purpose or content of the component for assistive technologies like screen readers. Use this to provide additional context when the visible content alone doesn't clearly convey what is progressing.
max	number	How much work the task requires in total. Must be greater than 0.
tone	"auto" | "neutral" | "info" | "success" | "caution" | "warning" | "critical"	The semantic meaning and color treatment of the component. - auto: Automatically determined based on context. - neutral: General information without specific intent. - info: Informational content or helpful tips. - success: Positive outcomes or successful states. - caution: Advisory notices that need attention. - warning: Important warnings about potential issues. - critical: Urgent problems or destructive actions.
value	number	How much of the task has been completed, as a number between 0 and max. Without a value the progress is indeterminate: the task is ongoing with no indication of how long it is expected to take.