# Spinner

Spinners signify that the application is waiting for an asynchronous operation to complete.

## Guidance

### When to use

- To indicate a loading state for quick asynchronous tasks

### When to consider alternatives

- When the process it is waiting for takes a long time. Spinners provide no feedback other than that _we're waiting_, so long processes can make users nervous that something went wrong. Consider adding descriptive text or another UX pattern entirely.
- When you are loading a whole page of content. If all you show the user is a spinner, the user may spend several seconds watching the spinner to be surprised with all the content all at once. Consider using a [_skeleton screen_](https://www.lukew.com/ff/entry.asp?1797) so the user knows what to expect.

### Usage

- If the process takes a long time, use something else.

### Accessibility

- The Spinner element should have an [`aria-valuetext`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-valuetext) attribute with a value of `loading` to provide a human readable text alternative for screen readers.
- When placed within a parent container, the parent element should include several ARIA attributes: `aria-relevant`, `aria-live`, and optionally `aria-atomic`.
  - `aria-relevant` may include `additions`, `text`, and `removals`. If a section will have items added or removed, use `additions removals`. If there will be additions or text changes without explicit removals, use `additions text`.
  - `aria-live` should be set to `polite` for a screen reader to speak the changes whenever the user is idle. `aria-live="assertive"` should only be used in situations that require a user’s immediate attention.
  - By default, a screen reader will only speak the contents of a changed node, and not the entire contents of the element. Set `aria-atomic="true"` for cases, such as an address, where a screen reader should read the contents of the entire element.

## Learn more

- [Response Times](https://www.nngroup.com/articles/response-times-3-important-limits/)
- [Progress Indicators](https://www.nngroup.com/articles/progress-indicators/)
- [GOV.UK Loading patterns discussion](https://paper.dropbox.com/doc/Loading-patterns-v0x8Xych1PbZQXOlbP3L6)
- [Avoid the Spinner](https://www.lukew.com/ff/entry.asp?1797)
- [ARIA Live Regions](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)