Progress & Spinners

You’re exporting a year of bank statements for your tax advisor. The bar shoots to 99% in ten seconds… and stays there. One minute. Five minutes. There’s no Cancel, and the sheet covers the whole app. You force-quit, open the app again and start over. Later you learn the export had failed at the very first second: the bar was just a timer.

Progress indicators are tiny, and they’re everywhere: behind every login, upload, payment and export. Their job is to answer two questions honestly: “Is it still working?” and “How long will it take?” When they lie, flash or never stop, users lose trust in everything else. Let’s learn how to test them.

What is it?

A progress indicator shows that the app is busy with something the user is waiting for. It comes in two kinds:

• A spinner (also called an activity indicator or loader) says: “I’m working, I don’t know how long it takes.”
• A progress bar says: “I’m working, and I’m this far.”

It’s one form of the loading stateLoading stateWhat the UI shows while it waits for data or an action to finish, such as a spinner or skeleton.Open in glossary →. Two close relatives have their own pages: the loading state inside a button is covered on Button, and skeletons for loading whole screens are on Empty & error states. This page is about the indicators themselves and their timing.

Anatomy

Determinate vs indeterminate

This is the most important distinction on the page:

An indeterminate indicator can switch to determinate once the app knows the size of the work: “Preparing…” with a spinner, then “Uploading 1 of 8” with a bar. The other way round (a bar that turns into an endless spinner at 99%) is a classic bug.

Linear vs circular

The shape is a layout choice, not a meaning:

• Linear (a bar) fits in a row, a card, under a toolbar or at the top of a web page. It has room for a label and “2 min left”.
• Circular (a spinner or ring) fits in small, square places: a button, a list row, the middle of an empty screen, a download icon.

Both shapes exist in both kinds: a determinate ring (like a download in an app store) and an indeterminate bar (like the thin moving line under a browser’s address bar).

How it differs from similar components

Designs & variants

When to use it

Show a progress indicator when the user asked for something and is waiting for it:

• Waiting for a server: signing in, placing an order, searching, loading a screen.
• Moving data: uploading photos, downloading a file, syncing, backing up.
• Long local work: exporting a video, applying a filter, installing an update.

How long the wait is decides what to show. These limits come from decades of usability research (Jakob Nielsen’s classic 0.1 s / 1 s / 10 s response times) and are still the best rule of thumb:

Good and bad uses

How good progress indicators behave

They don’t flash

An indicator that appears and disappears within a few frames is worse than none: the screen flickers, layouts jump, and the app feels slower. Good apps use two timers together:

The exact numbers vary by team and design system. What you test is the behavior: no flashes on a fast network, an indicator within about a second on a slow one.

Long work shows real progress, and can be canceled

For anything that can take more than about ten seconds:

• Use a determinate bar if the work can be measured, with a label (“Uploading 3 of 8 photos”) and, ideally, time left.
• Offer Cancel, and make it real: it stops the upload or export on the device and the server, leaves no half-finished files, and says what happened (“Export canceled”).
• Don’t block the whole app if you don’t have to. Let the export run while the user keeps browsing, and tell them when it’s done.
• Check what happens if the user leaves: the back gesture, switching apps, locking the phone. Does the work continue, pause, or silently die? See Background & foreground.

Progress tells the truth

A determinate indicator makes a promise. Test that it keeps it:

• It only moves forward. A percentage that jumps from 46% to 31% usually means the app divided “done so far” by a total that changed.
• It reaches 100% when the work is done, and the work is really done then (the file is in the folder, the order exists).
• It doesn’t race to 99% and wait. Many apps fake the bar on a timer and only finish when the server answers. If that answer is an error, the bar sits at 99% forever.
• The label matches the bar: “7 of 12” next to 30% is a contradiction.
• Time left is roughly right and goes down, not “about 2 min left” for five minutes.

It always ends, including on errors

Every indicator needs an exit for each outcome:

For long work, a good timeout watches for no progress rather than total time: a 30-second export that keeps moving is fine, an upload stuck at 35% for 8 seconds is not. Many apps first say “This is taking longer than usual…” and then give up with an error. The pages on Empty & error states and Network conditions cover the error side in depth.

Try it: timing lab

A correct photo export with knobs for every timing rule. Pick a duration, tap Export album, and read the Last run timeline after each run. Some things to try:

• 100 ms with everything off: the timeline says “Flash!”. Now turn on the delay (no indicator at all), or instead the minimum display (it stays 500 ms).
• 30 s with the spinner, then with the progress bar. Hide Cancel and feel what it’s like to be stuck.
• Never finishes and Fails: watch how the indicator ends, and what VoiceOver hears.

Common bugs

Find the bug

This banking app has six bugs in its loading and progress indicators. Time runs 8× faster than in the real app, so the “2-minute” export takes about 15 seconds. Explore it like a tester:

• Open a few statements and watch the screen closely while you tap.
• Export 2025 and watch the percentage and the time left the whole way. Is there a way out?
• Turn on server errors, then export again and refresh the balance.
• Turn on the VoiceOver caption panel and finish an export. Read the panel.

How to test it

Checklist

Example test cases

Tools

• Slow it down: network throttlingNetwork throttlingDeliberately slowing the connection to test how an app behaves on poor networks.Open in glossary → (Network Link Conditioner on iOS, the emulator’s network settings on Android, the “Fast 4G”, “Slow 4G” and “3G” presets in Chrome DevTools) shows you the indicator at all. Fast office Wi-Fi hides most of these bugs.
• Break it on purpose: a proxy tool like Charles or Proxyman can return a 500, add a long delay, or hold a request with a proxy breakpointProxy breakpointPausing a request or response in a proxy tool so you can edit it before it continues.Open in glossary → so it never answers. That’s how you find endless spinners and the 99% bug.
• Catch flashes: record the screen and step through frame by frame (QuickTime, the iOS screen recorder, adb shell screenrecord). A 60 ms flash is three or four frames.
• Check it’s real: after “100%”, check the result exists (the file in Files, the order in the history). After Cancel, check the proxy log: did requests really stop?
• Web: DevTools › Network shows request timing; the Performance panel’s screenshots show flashes and layout shifts.

Accessibility

• Give it a name. A spinner alone means nothing to a screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary →. Label it with what’s happening: “Loading statements”, “Uploading 3 of 8 photos”.
  Dev note

  On the web, the native <progress> has the progressbar role built in; a custom bar needs role="progressbar", a label (aria-label or aria-labelledby), aria-valuemin, aria-valuemax and aria-valuenow. Add aria-valuetext when a number isn’t the clearest wording (“5 of 8 photos”). For an indeterminate bar, leave out aria-valuenow. aria-busy="true" on a list or region that’s being updated tells assistive technology to wait until it’s done.
• Announce the result. Screen readers usually don’t read every change of a progress bar unless it has focus, and reading every percent would be unbearable anyway. Announce the start, maybe a few milestones for long work, and always the end: “Export complete”, “Upload failed”. This is WCAGWCAGThe Web Content Accessibility Guidelines, the main international standard for accessibility.Open in glossary → 4.1.3 Status Messages (AA).
  Dev note

  On the web use a live region (role="status"), on iOS an accessibility announcement, on Android an announcement or a live region.
• Don’t steal focus to announce progress. Focus should stay where the user is.
• reduced motionReduced motionThe OS setting, and the prefers-reduced-motion media query, that ask apps to minimize animation.Open in glossary →. A small loading spinner is usually considered essential motion and may keep turning, but large or decorative motion (bouncing loaders, shimmering skeletons, confetti at 100%) should calm down. Watch out for the opposite bug: some sites switch off all animation with Reduce Motion, which freezes a CSS spinner. That’s only OK if a text label still says “Loading…”.
• Contrast. The bar and its track are UI parts: at least 3:1 against the background (WCAG 1.4.11 Non-text Contrast, AA). A pale grey bar on white fails. Any percentage text needs 4.5:1 (WCAG 1.4.3 Contrast (Minimum), AA).
• Cancel must be reachable by keyboard, Switch Control and screen readers, not just by tapping a tiny “x”. At least 44×44 pt on iOS and 48×48 dp on Android. On the web, WCAG 2.5.8 (AA) asks for at least 24×24 CSS px; 44×44 px (2.5.5, AAA) is the comfortable target.

Mobile vs web

Check your understanding