WebTech1223411 logo WebTech1223411Web tech, read closely
Accessibility

Accessible Loading States for Slow API Responses

A checkout button on a project I helped with took a median of 900 milliseconds to come back and a p95 of 4.2 seconds, which is ordinary for anything that talks to a payment provider.

A browser window showing a disabled submit button with a spinner beside a screen reader speech output panel

A checkout button on a project I helped with took a median of 900 milliseconds to come back and a p95 of 4.2 seconds, which is ordinary for anything that talks to a payment provider. The front end handled it the usual way: swap the button label for a spinner, disable the button, done. In an audit a screen reader user pressed submit, heard absolutely nothing, waited two seconds, and pressed it again. The idempotency key on the back end is the only reason that did not create two orders.

Slow responses are a back end reality that the front end has to narrate. Nobody writes a ticket called announce the waiting state, so it never gets built, and the result is a class of bug that passes every automated scan. A spinner is a picture of waiting. It is not a message, and by default it produces no output in assistive technology at all.

What Assistive Technology Hears By Default

Nothing. That is the whole answer, and it surprises people. When JavaScript replaces the contents of a div, the accessibility tree updates, but no announcement is generated. A screen reader reads what the user navigates to, plus anything the page explicitly asks to be announced. A spinner appearing in the DOM asks for nothing.

Two secondary problems ride along with it. If you replace the button's text with an icon, the button loses its accessible name mid interaction, so a user who tabs back to it hears an unlabelled button. If you set the button to disabled, it leaves the tab order entirely, which means the element the user was just on vanishes from under them and focus falls back to the body in some browsers.

Keyboard users who can see the screen are better off, but not by much. Sighted keyboard users often lose track of where focus went when a section of the page is swapped for a skeleton, and anyone using screen magnification at 400 percent may be looking at a part of the viewport where the spinner is not visible at all.

Live Regions Do Less Than Most Docs Suggest

The mechanism for announcing a change is a live region, and it has one rule people break constantly: the container must already be in the DOM and already be recognised as a live region before you put text into it. If you inject <div aria-live="polite">Loading</div> in one go, most screen readers announce nothing, because the region was born with its content and no change was observed.

So render an empty live region when the component mounts, then write text into it. Keep it in the markup even when empty. The practical form is a single visually hidden element with role="status", which carries an implicit polite setting, placed near the control it describes.

Politeness matters more than it sounds. aria-live="polite" queues the announcement until the user stops interacting, which is what you want for loading and success. aria-live="assertive" interrupts immediately, cutting off whatever the user was listening to, and it belongs to errors and genuinely time critical changes. Marking a loading message assertive is a common mistake and it makes the page feel like it is talking over you.

aria-busy="true" on a region tells assistive technology that the contents are mid update and announcements should be held until it flips back to false. It is useful for a large region being rebuilt in several steps. It does not announce anything on its own, and setting it on a spinner achieves nothing.

Three Patterns, Matched To How Long The Wait Is

The old interaction thresholds still hold up: under 100 milliseconds feels instant, up to about one second feels like a direct response, and past roughly ten seconds attention is gone. Loading states should follow those bands rather than fire the same way for every request.

WaitWhat to doWhat to announce
Under 500 msNothing visible, no spinnerOnly the result
500 ms to 4 sIn place spinner, button stays focusable with aria-disabledOne polite message, then the result
4 s to 15 sSkeleton or progress text with a countPolite update at start, then at completion
Over 15 sBackground job plus a way to leave the pageProgress at intervals, final state assertive

The 500 millisecond delay before showing anything is the single best change I have made to loading UX. Start a timer on request, and only render the spinner if the response has not arrived. Most requests on a warm cache never show one, which removes the flash of a spinner that appears and disappears within 80 milliseconds and, in a live region, produces an announcement for a wait the user never experienced.

Why Announcing Every State Change Backfires

The advice in most accessibility checklists is to announce state changes, and taken literally it produces a page that will not shut up. On a dashboard I reviewed, six widgets each loaded independently and each announced itself. A screen reader user landing on that page heard six loading messages, then six loaded messages, in an order determined by network timing, before they could read anything. The information content of that was zero.

Announce at the level the user acted at, not the level your components are built at. One user action produces at most one loading announcement and one result announcement. If six panels refresh because the user pressed one button, write one message into one live region: Updating six panels, then Six panels updated. Panels that load on page arrival without any user action should announce nothing, because the user did not ask and the content will be read when they reach it.

The other overused pattern is moving focus to the spinner or the result. Moving focus is correct when the user explicitly navigated, as with a route change or opening a dialog. It is wrong for an inline update, since it yanks the user out of position and, in a form, away from the field they were about to correct. Leave focus alone and let the live region do the talking.

What The Back End Owes The Front End

Half of this problem is an API design problem. A request that can take 30 seconds should not be a synchronous call that the browser holds open. Return a job id quickly, then let the client poll or subscribe, so the interface can report real progress instead of guessing.

Three things make the front end's job possible. Send a timeout you both agree on, so the client can show a real failure instead of a spinner that spins forever, and keep it under the proxy timeout rather than over it. Return a count where you have one, since Loaded 40 of 120 orders is announceable and a spinner is not. Make write endpoints safe to retry, because a user who hears nothing will press the button again, and the accessible fix and the duplicate request fix are the same fix.

When you are trying to work out which part of the chain is slow in the first place, timing the call outside the browser is faster than guessing from the network panel, and timing slow API requests with curl covers the format string I use against a local $API_URL/v1/orders route.

A Ten Minute Test Pass

Throttle the network in DevTools to Slow 3G, which turns every one of these states from theoretical into visible. Then do four things with the keyboard only. Trigger the slow action and check that focus is still somewhere sensible afterwards. Tab to the button mid request and confirm it still has a name and still reports as busy or disabled rather than disappearing. Turn on a screen reader, NVDA on Windows or VoiceOver on macOS, and count the announcements: you want one for the wait and one for the result. Finally, make the request fail, by blocking the request URL in DevTools, and confirm the error is announced assertively and describes what to do next, which is the same discipline as accessible form error messages.

If an announcement does not arrive, inspect the region in the DevTools accessibility tree before changing any code. Nine times out of ten the region was created in the same tick as its text, and moving the empty container into the initial render fixes it without any new attributes.

FAQ

Should I use role="status" or aria-live="polite"?

role="status" is the shorter way to get polite announcements plus an implicit landmark, and it is what I reach for first. Use the explicit aria-live attribute when you need to combine settings, such as pairing polite with aria-atomic="true" so the whole region is read rather than just the changed words.

Do I still need visually hidden text if the spinner has an aria-label?

Yes, because a label on an element that nobody navigates to is never read. Labels describe things users reach. Live regions announce things that happen without being reached, and a loading state is the second kind.

How do I handle a request that never comes back?

Set a client timeout, 15 to 30 seconds for most interactive calls, and treat the timeout as an error state with an assertive announcement and a retry control. A spinner with no end is worse than an error message, since it gives the user nothing to act on.

Are skeleton screens accessible?

They are fine visually and invisible to a screen reader, which is the correct outcome as long as a live region covers the announcement. Mark the skeleton container aria-hidden="true" so its placeholder shapes do not get read as empty list items, and keep prefers-reduced-motion in mind, since shimmering skeletons are animation.

KO
Kofi Oosterhuis

Kofi spent years keeping APIs and game servers alive through traffic spikes and the occasional bad deploy. He covers back-end design, scaling and networking, with a preference for boring systems that do not page anyone at night.

More posts by Kofi

More in Accessibility

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto