Progress Bar

Visual Variants

Semantic Variants

Size Variants

Animation Variants

• Determinate: Smooth transition from current value to new value using CSS transition or a spring animation. Preview easing curves with the Animation & Easing Tool.
• Indeterminate: A looping animation — typically a shimmer, pulse, or sliding gradient that moves left-to-right continuously. Use @keyframes with translateX for performance (GPU-accelerated).
• Buffer: Two layers — a primary fill showing actual progress and a secondary (lighter) fill showing buffered/pre-loaded progress. Common in video players.
• Striped: Diagonal stripes animated across the fill, indicating active processing. Popular in Bootstrap-style systems.

Progress Bar Properties

Important: For determinate progress bars, always provide a meaningful value. Screen readers announce progress changes; jumping from 0% to 100% instantly defeats the purpose. Update in reasonable increments (1–5%) for smooth, informative feedback.

Design Token Mappings

Progress bars are deceptively token-rich — they touch color, spacing, motion, and border-radius. For a deep understanding of token architecture, see our Design Tokens Complete Guide.

Dynamic Color Tokens

Many progress bars shift color as they approach thresholds. Map these to semantic tokens:

/* Auto-color based on value */
--progress-fill: var(--color-primary-500);        /* 0–69% */
--progress-fill-warning: var(--color-warning-500); /* 70–89% */
--progress-fill-danger: var(--color-error-500);    /* 90–100% */

This pattern is common for storage quotas, bandwidth meters, and capacity indicators. Generate all three scales from a single hue using the Color Palette Generator.

Progress Bar States

Accessibility — Progress Bar

Progress bars are straightforward to make accessible, but there are important nuances around live announcements and labeling. Validate your color choices with the Contrast Checker.

ARIA Pattern

Use the native <progress> element when possible — it provides built-in semantics. For custom-styled bars, use role="progressbar":

<!-- Native HTML -->
<label for="file-upload">Uploading document.pdf</label>
<progress id="file-upload" value="65" max="100">65%</progress>

<!-- Custom ARIA -->
<div role="progressbar"
     aria-valuenow="65"
     aria-valuemin="0"
     aria-valuemax="100"
     aria-label="Uploading document.pdf">
  <div class="progress-fill" style="width: 65%"></div>
</div>

WCAG Success Criteria

Live Announcements

Screen readers poll role="progressbar" periodically, but the frequency varies. For critical progress (file uploads, form submissions), supplement with an aria-live region:

<div aria-live="polite" class="sr-only">
  Upload progress: 65% complete
</div>

Don't announce every 1% increment — this floods the screen reader. Announce at meaningful intervals: 25%, 50%, 75%, 100%, and on error.

Indeterminate Accessibility

For indeterminate progress bars, omit aria-valuenow (don't set it to 0, which implies "no progress"). Set aria-busy="true" on the content region being loaded, and provide a text label like "Loading…":

<div role="progressbar" aria-label="Loading data…">
  <!-- animated indeterminate bar -->
</div>
<div aria-busy="true">
  <!-- content area being loaded -->
</div>

Do

• Always show determinate progress when you can. If you know the total, show percentage. Users strongly prefer knowing "65% done" over an indefinite spinner.
• Use smooth transitions between value updates — jumping from 30% to 60% instantly feels broken. Apply transition: width 300ms ease-out. Preview with the Animation & Easing Tool.
• Label your progress bars. Even a simple "Uploading… 65%" dramatically improves usability. Place labels above, below, or inside the bar depending on size.
• Provide time estimates when possible. "Uploading… 65% — about 2 minutes remaining" is the gold standard.
• Use semantic colors for thresholds. Storage at 50%? Blue. At 85%? Amber. At 95%? Red. Generate consistent color scales with the Color Palette Generator.
• Consider the thin page-top bar for route changes in SPAs — it's a well-established pattern (GitHub, YouTube) that doesn't take up layout space.

Don't

• Don't fake progress. If you simulate progress that doesn't correlate with actual work, users will notice when it stalls at 99%. It destroys trust.
• Don't show progress bars for operations under 1 second. The bar will flash and disappear, which is more distracting than helpful.
• Don't use a progress bar when you have no progress data. Use a Spinner or Skeleton for indeterminate loading.
• Don't restart progress from 0% unless the operation has genuinely restarted. Backward movement feels like regression.
• Don't hide the bar while it's in progress. If the user navigates away, either continue in the background with a notification or confirm they want to cancel.
• Don't rely only on color for state changes — supplement with labels or icons for colorblind users (WCAG 1.4.1).

Content Guidelines

• Label text should describe what's happening: "Uploading document.pdf" not just "Loading"
• Percentage text should be right-aligned or inside the bar
• For multi-step processes, show "Step 3 of 5" alongside the bar
• Error states should describe what went wrong and offer a retry action

Design System Implementations

Material Design 3 offers both linear and circular progress indicators with determinate and indeterminate variants. The linear variant uses a thin 4px track by default, with the indeterminate animation consisting of two bars that grow and shrink independently — a nuanced animation that feels more natural than a simple slide. Material also provides a "buffer" variant with a secondary track for pre-loading states (common in video players). The circular variant is their spinner equivalent, doubling as both progress indicator and loading spinner depending on whether you provide a value.

Ant Design provides a Progress component with line, circle, and dashboard (semicircle) types. It supports steps for segmented progress, strokeColor for custom gradients (pass an object with from and to), and a format prop for custom value display. Ant's success prop lets you define a sub-section within the bar that's colored green — useful for showing "completed" vs "in progress" portions separately.

Chakra UI's Progress component supports hasStripe and isAnimated props for the classic Bootstrap-style striped animation. It also supports the colorScheme prop to change the fill color and isIndeterminate for the looping animation. Chakra uses the native <div> approach with ARIA roles rather than the <progress> element, giving full styling control.

Bootstrap's progress bar is perhaps the most widely recognized implementation. It introduced the striped/animated pattern that many design systems have adopted. Bootstrap uses a .progress container with .progress-bar inner div, supports stacking multiple bars within one container for multi-part progress, and offers contextual classes (bg-success, bg-warning, bg-danger).

Shadcn/ui keeps it minimal: a track and fill with Tailwind classes. The component is a thin wrapper around a styled div. No built-in indeterminate, striped, or circular variants — compose those yourself.

Radix UI provides a Progress primitive with value and max props, along with ProgressIndicator as a child for the fill. It handles all ARIA attributes automatically and leaves styling entirely to you. It correctly omits aria-valuenow when value is null (indeterminate).

For choosing fill colors that maintain contrast across all variants and themes, use the Color Palette Generator. Preview animation easing with the Animation & Easing Tool.