Loading indicator

Category: Communication
Tokens: comp.loading-indicator
Level: Base

Overview

Web: tanrei-loading-indicator; schedule
SwiftUI: TanreiLoadingIndicator; schedule
Jetpack Compose: TanreiLoadingIndicator; schedule
Flutter: TanreiLoadingIndicator; schedule
React Native: LoadingIndicator; schedule

Generated from docs/status/status.json, specs/loading-indicator.spec.json

A revised spec, not yet on every platform

This page describes the loading indicator as the spec has it now: it waits before it is shown, then enters. The web component already does, and so do the demos, which appear after the delay. SwiftUI, Compose, Flutter and React Native are marked lagging above: until they catch up they draw and expose the indicator as soon as it is inserted, and do not take the three new props, so their samples below show only what they ship.

Inline and contained

Usage

<section aria-busy="true">
  <tanrei-loading-indicator label="Loading messages"></tanrei-loading-indicator>
</section>

<!-- Contained: on a raised circle of its own, over content. -->
<tanrei-loading-indicator contained size="large" label="Refreshing"></tanrei-loading-indicator>

<!-- A busy button answers the press at once: no delay. -->
<tanrei-loading-indicator size="small" show-delay="0" label="Saving"></tanrei-loading-indicator>

<!-- Another pace for one indicator: wait longer, then grow in. -->
<tanrei-loading-indicator show-delay="600" entrance="grow" label="Loading the report"></tanrei-loading-indicator>

<script type="module">
  import '@tanrei/web/components/loading-indicator';
</script>

import { LoadingIndicator } from '@tanrei/react';

<section aria-busy={loading}>
  {loading ? <LoadingIndicator label="Loading messages" /> : <MessageList />}
</section>
<LoadingIndicator contained size="large" label="Refreshing" />
<LoadingIndicator size="small" showDelay={0} label="Saving" />
<LoadingIndicator showDelay={600} entrance="grow" label="Loading the report" />

import Tanrei

TanreiLoadingIndicator("Loading messages")

// Over content, on its own raised container.
TanreiLoadingIndicator("Refreshing", size: .large, contained: true)

import io.github.chnotchy.tanrei.components.TanreiContainedLoadingIndicator
import io.github.chnotchy.tanrei.components.TanreiLoadingIndicator
import io.github.chnotchy.tanrei.tokens.TanreiLoadingIndicatorSize

TanreiLoadingIndicator(contentDescription = "Loading messages")

// Contained is a second composable with the same parameters.
TanreiContainedLoadingIndicator(contentDescription = "Refreshing", size = TanreiLoadingIndicatorSize.Large)

import 'package:tanrei/tanrei.dart';

const TanreiLoadingIndicator(semanticsLabel: 'Loading messages');
const TanreiLoadingIndicator(
  semanticsLabel: 'Refreshing',
  size: TanreiLoadingIndicatorSize.large,
  contained: true,
);

import { LoadingIndicator } from '@tanrei/react-native';

<LoadingIndicator accessibilityLabel="Loading messages" />
<LoadingIndicator accessibilityLabel="Refreshing" size="large" contained />

Specs

Sizes, inline and contained

Anatomy

Drawn over the fixture small, as the web package draws it.

Part	Description
1 `indicator`	The moving mark: an arc a quarter of a circle long that turns. It has no track, because there is no value to read.
2 `container` · optional	A filled, raised circle behind the indicator, drawn only when contained, so the indicator can be seen over content.

Measurements

Length	Token	Value (px)
`indicator` size	`tanrei.comp.loading-indicator.indicator.size.small`	16

Drawn over the fixture small, as the web package draws it.

Properties

Property	Type	Default	Description
`size`	`small` \| `medium` \| `large`	`"medium"`	The indicator's box (16 / 24 / 40): small replaces an icon in a control, medium sits next to text, large fills an empty section. Contained, the container is 24 / 32 / 48. A design system may add values.
`contained`	`boolean`	`false`	Draws the indicator on a raised container of its own, for places where it floats over content (pull to refresh, over an image or a list).
`label`	`string`	`""`	The accessible name: what is loading ("Loading messages"). Required: a moving mark alone is not a name.
`showDelay`	`number`	`null`	How long, in milliseconds, this indicator waits from the moment it is inserted before it is drawn and exposed to assistive technology; 0 shows it as it is inserted. Null takes comp.loading-indicator.motion.show-delay, the system's answer for every indicator. Set it only where one indicator needs another pace than the rest (a wait the product knows is never instant, a busy button that should answer the press at once).
`entrance`	`auto` \| `fade` \| `grow`	`"auto"`	How this indicator enters once its show delay has passed: fade eases it in, grow eases it in while it grows from its center. Auto takes comp.loading-indicator.motion.entrance, the system's answer for every indicator. Under reduced motion grow enters as fade (LDG-13).
`enterDuration`	`number`	`null`	How long, in milliseconds, this indicator's entrance lasts; 0 shows it whole at once. Null takes comp.loading-indicator.motion.enter-duration.

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID	Requirement
`LDG-1`	THE loading indicator SHALL draw, inside a comp.loading-indicator.indicator.size.medium square for medium (and so on for each size), an arc a quarter of the circle long with round caps and a stroke of comp.loading-indicator.indicator.thickness.medium for medium (and so on), whose outer edge touches the square, and SHALL turn it clockwise once per comp.loading-indicator.motion.cycle-duration at constant speed (sys.motion.easing.linear); it SHALL draw no track.
`LDG-2`	WHILE contained is false THE loading indicator SHALL take exactly its indicator square, draw no container, and draw the arc in comp.loading-indicator.indicator.color.
`LDG-3`	WHILE contained is true THE loading indicator SHALL draw a container of comp.loading-indicator.container.size.medium for medium (and so on for each size) with corners of comp.loading-indicator.container.shape, filled with comp.loading-indicator.contained.container.color and raised by comp.loading-indicator.contained.container.elevation, center the indicator in it, and draw the arc in comp.loading-indicator.contained.indicator.color.
`LDG-4`	WHERE reduced motion is requested THE loading indicator SHALL NOT turn: it SHALL draw the whole circle at the indicator's size and stroke and ease its opacity from 1 to 0 and back to 1 once per comp.loading-indicator.motion.cycle-duration with sys.motion.easing.standard; a container, when contained, SHALL stay still and opaque.
`LDG-5`	WHILE the loading indicator is shown (LDG-12) THE loading indicator SHALL expose the progressbar role to assistive technology with label as its name, no current value, and the platform's busy or indeterminate state.
`LDG-6`	THE loading indicator SHALL NOT be focusable and SHALL NOT announce itself when it appears or disappears; the region being loaded is marked busy, and its completion announced, by the product.
`LDG-7`	WHILE the loading indicator is not visible (scrolled out of view, in a hidden view, or in an app in the background) THE loading indicator SHALL NOT run its animation, and SHALL resume it when it becomes visible.
`LDG-8`	WHERE the layout direction is right-to-left THE loading indicator SHALL NOT be mirrored: it turns clockwise in every direction.
`LDG-9`	WHEN size names a value that the active design system does not have THE loading indicator SHALL render with the default value's tokens, and in debug builds report the unknown value.
`LDG-10`	WHILE label is empty THE loading indicator SHALL still render, and in debug builds report that it has no accessible name.
`LDG-11`	WHEN the loading indicator is inserted into a view THE loading indicator SHALL wait for its show delay (LDG-14) before it is shown, and WHILE it waits SHALL draw nothing (no indicator, no container, no shadow), SHALL run no animation, SHALL be absent from the accessibility tree (no role, no name, no busy state), and SHALL still take the box it takes when shown (LDG-2, LDG-3), so that nothing around it moves when it appears; a show delay of 0 SHALL show it as it is inserted.
`LDG-12`	WHEN its show delay ends THE loading indicator SHALL be shown: it SHALL expose itself as LDG-5 says, without announcing itself (LDG-6), start its entrance (LDG-13), and start the turn of LDG-1, or the pulse of LDG-4, at the beginning of a cycle.
`LDG-13`	WHEN the loading indicator is shown THE loading indicator SHALL enter over its enter duration (LDG-14) with comp.loading-indicator.motion.enter-easing, as its entrance names: fade SHALL ease the opacity of the whole component (the indicator and, when contained, the container and its shadow) from 0 to 1, and grow SHALL ease the opacity the same way while scaling the whole component from nothing to its full size about its center, on the same curve over the same time. The entrance SHALL be drawn only: the box SHALL keep its full size throughout, and the entrance SHALL run to its end whether or not the indicator is visible (LDG-7 pauses the cycle, not the entrance). An enter duration of 0 SHALL show the indicator whole at once. WHERE reduced motion is requested THE loading indicator SHALL NOT scale: grow SHALL enter as fade, and on a platform whose reduced-motion setting removes every animation (Android's) the indicator SHALL appear at once.
`LDG-14`	THE loading indicator SHALL take its show delay from showDelay and its enter duration from enterDuration, each a number of milliseconds used as given (the motion dial does not scale it), and its kind of entrance from entrance. WHILE showDelay or enterDuration is null THE loading indicator SHALL use comp.loading-indicator.motion.show-delay or comp.loading-indicator.motion.enter-duration in its place, and WHILE entrance is auto it SHALL use comp.loading-indicator.motion.entrance; IF showDelay or enterDuration is negative or not a finite number, or entrance names a kind the indicator does not know, THE loading indicator SHALL use the token likewise and in debug builds report the value it ignored.
`LDG-15`	THE loading indicator SHALL treat its show delay as a waiting time, not motion: WHERE motion is reduced it SHALL keep it, on every platform, including one whose reduced-motion setting removes every animation; and it SHALL keep counting it while the indicator cannot be seen (scrolled out of view, in a hidden view), because the delay measures the wait, not what is seen.
`LDG-16`	WHEN the loading indicator is removed before its show delay ends THE loading indicator SHALL have drawn, exposed and announced nothing, and WHEN it is removed while shown, during its entrance included, it SHALL disappear at once. WHEN it is inserted again THE loading indicator SHALL wait its whole show delay again; hiding it without removing it (a hidden ancestor, scrolling) SHALL neither restart nor pause the delay (LDG-15). WHEN showDelay, entrance or enterDuration changes while the delay or the entrance is running THE loading indicator SHALL finish the running one as it started and use the new value from its next insertion.
`LDG-17`	THE loading indicator SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the loading indicator is shown THE loading indicator SHALL draw itself for the new direction at once, without a motion of its own, keeping its place in its cycle.
`LDG-18`	WHERE the platform has ARIA attributes (the web), the host carries its progressbar role (LDG-5) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE loading indicator SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (LDG-10). WHILE it waits to be shown (LDG-11) it has no role, and SHALL hold them as well, so that nothing names an element with no role, and give them back when it is shown. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE loading indicator SHALL take it away.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Component	`tanrei-loading-indicator`	`TanreiLoadingIndicator`	`TanreiLoadingIndicator`	`TanreiLoadingIndicator`	`LoadingIndicator`
`size` · Property	`size`	`size`	`size`	`size`	`size`
`contained` · Property	`contained`	`contained`	`TanreiContainedLoadingIndicator`	`contained`	`contained`
`label` · Property	`label`	`label`	`contentDescription`	`semanticsLabel`	`accessibilityLabel`
`showDelay` · Property	`showDelay`	`showDelay`	`showDelayMillis`	`showDelay`	`showDelay`
`entrance` · Property	`entrance`	`entrance`	`entrance`	`entrance`	`entrance`
`enterDuration` · Property	`enterDuration`	`enterDuration`	`enterDurationMillis`	`enterDuration`	`enterDuration`
Notes	The host carries `role="progressbar"`, `aria-label` and `aria-busy="true"` once shown, and no aria-value attributes; during the show delay it carries none of them and is `aria-hidden="true"`, and its parts are `visibility: hidden` while the host keeps its size (LDG-11). The delay starts in `connectedCallback` and is cancelled in `disconnectedCallback`, so moving the element within the document starts a new delay; hiding it with `hidden` or CSS does not (LDG-16) — insert and remove it with the wait. `showDelay` and `enterDuration` are number properties in milliseconds, null by default, set by the `show-delay` and `enter-duration` attributes; an attribute that is empty or does not parse as a finite number is not a number (LDG-14), so `show-delay=""` takes the token and does not show at once. `entrance` is a string property and attribute, `auto` by default; `auto` reads `--tanrei-comp-loading-indicator-motion-entrance` from the cascade, which carries the choice's name. The arc turns with a CSS animation that `@media (prefers-reduced-motion: reduce)` replaces, and pauses while the element is not intersecting the viewport. Snapshot harness: each fixture is rendered with `show-delay="0"` and `enter-duration="0"` (LDG-11).	Lagging: ships the earlier spec, drawn and exposed as it is inserted, with no delay or entrance; owes LDG-5's revision and LDG-11 to LDG-16. The target: `TanreiLoadingIndicator(_ label:, size:, contained:, showDelay: Duration? = nil, entrance: TanreiLoadingEntrance? = nil, enterDuration: Duration? = nil)`; a `Duration` carries its own unit (`.milliseconds(300)`), nil takes the token (nil is also `entrance`'s auto), and a negative one takes the token and is reported in debug builds. The delay is a `.task` bound to the view's identity (cancelled when the view leaves the hierarchy), and the view is `.accessibilityHidden(true)` and at zero opacity until it ends, keeping its frame. Reduced motion is `accessibilityReduceMotion` from the environment. Snapshot harness: renders each fixture with `showDelay: .zero` and `enterDuration: .zero`.	Lagging: ships the earlier spec, drawn and exposed as it is inserted, with no delay or entrance; owes LDG-5's revision and LDG-11 to LDG-16. The target adds `showDelayMillis: Long? = null`, `entrance: TanreiLoadingEntrance? = null` (null is auto) and `enterDurationMillis: Long? = null` to both composables, named in milliseconds as `ViewConfiguration.longPressTimeoutMillis` is; null takes the token, a negative value takes the token and is reported in debug builds. The delay is a coroutine `delay` in a `LaunchedEffect` started when the indicator enters the composition, not an animation, so the animator duration scale of 0 (Android's reduced motion) does not remove it (LDG-15); until it ends the layout keeps its size, draws nothing, and its semantics are cleared. Compose idiom, as Material's `LoadingIndicator` and `ContainedLoadingIndicator`: contained is a second composable, `TanreiContainedLoadingIndicator`, with the same parameters, not a flag. Snapshot harness: renders each fixture with `showDelayMillis = 0` and `enterDurationMillis = 0`.	Lagging: ships the earlier spec, drawn and exposed as it is inserted, with no delay or entrance; owes LDG-5's revision and LDG-11 to LDG-16. The target adds `showDelay`, `entrance` (a `TanreiLoadingEntrance?`, null is auto) and `enterDuration`, the times as `Duration?`: null takes the token, a negative one takes the token and is reported in debug builds. The delay is a `Timer` started in `initState` and cancelled in `dispose`; until it ends the child keeps its size, paints nothing and is wrapped in `ExcludeSemantics`. `semanticsLabel` as Flutter's progress indicators name it. Reduced motion is `MediaQuery.disableAnimationsOf(context)`; the turning animation stops with `TickerMode`, which covers hidden routes, and the timer does not. Snapshot harness: a golden of each fixture with `showDelay: Duration.zero` and `enterDuration: Duration.zero`.	Lagging: ships the earlier spec, drawn and exposed as it is inserted, with no delay or entrance; owes LDG-5's revision and LDG-11 to LDG-16. The target: `showDelay` and `enterDuration` are numbers of milliseconds, as `Pressable`'s `delayLongPress` is; undefined or null takes the token, and a negative or non-finite number takes the token and is reported in development builds; `entrance` is `'auto' \| 'fade' \| 'grow'`, `'auto'` by default. The delay is a timer set when the component mounts and cleared when it unmounts; until it ends the view keeps its size at zero opacity with `accessibilityElementsHidden` and `importantForAccessibility="no-hide-descendants"`, and once shown it takes `accessibilityRole="progressbar"` with `accessibilityState={{ busy: true }}`. Reduced motion from `AccessibilityInfo.isReduceMotionEnabled()`. Not React Native's `ActivityIndicator`, which draws the platform's own spinner and cannot follow the tokens. Snapshot harness: renders each fixture with `showDelay={0}` and `enterDuration={0}`.

Tokens

Token	Aliases	Resolved (light)
`--tanrei-comp-loading-indicator-contained-container-color`	`sys.color.surface-container-lowest`	#ffffff
`--tanrei-comp-loading-indicator-contained-container-elevation`	`sys.elevation.level2`	0px 0px 0px 1px rgb(0 0 0 / 0.08), 0px 1px 2px 0px rgb(0 0 0 / 0.04)
`--tanrei-comp-loading-indicator-contained-indicator-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-loading-indicator-container-shape`	`sys.shape.corner.full`	9999px
`--tanrei-comp-loading-indicator-container-size-large`	—	48px
`--tanrei-comp-loading-indicator-container-size-medium`	—	32px
`--tanrei-comp-loading-indicator-container-size-small`	—	24px
`--tanrei-comp-loading-indicator-indicator-color`	`sys.color.on-surface-variant`	#4b4b4b
`--tanrei-comp-loading-indicator-indicator-size-large`	—	40px
`--tanrei-comp-loading-indicator-indicator-size-medium`	—	24px
`--tanrei-comp-loading-indicator-indicator-size-small`	—	16px
`--tanrei-comp-loading-indicator-indicator-thickness-large`	`sys.border.thick`	2px
`--tanrei-comp-loading-indicator-indicator-thickness-medium`	`sys.border.thick`	2px
`--tanrei-comp-loading-indicator-indicator-thickness-small`	`sys.border.thick`	2px
`--tanrei-comp-loading-indicator-motion-cycle-duration`	`sys.motion.duration.extra-long4`	1000ms
`--tanrei-comp-loading-indicator-motion-enter-duration`	`sys.motion.role.state.large`	250ms
`--tanrei-comp-loading-indicator-motion-enter-easing`	`sys.motion.easing.enter`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-loading-indicator-motion-entrance`	—	0
`--tanrei-comp-loading-indicator-motion-show-delay`	`sys.motion.role.show-delay`	300ms

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

`size: small` (2)

small

size: small label: Loading

contained-small

size: small contained: true label: Loading

`size: medium` (2)

medium

label: Loading

contained-medium

contained: true label: Loading

`size: large` (2)

large

size: large label: Loading

contained-large

size: large contained: true label: Loading

Generated from specs/loading-indicator.spec.json, tokens/comp/loading-indicator.tokens.json, design/tokens/

Guidelines

When to use

Use a loading indicator for a short wait whose length you cannot tell: a list fetching its next page, a control saving, a preview rendering. It says that something is happening and nothing about how long it will take.

When the wait may last more than a few seconds, or when you can measure how far it has come, use a progress indicator instead. A value, even a rough one, makes a long wait easier to bear.

Choosing a size

Size	Indicator / container in the default system	Use for
Small	16 / 24	In place of an icon in a control, such as a button that is saving.
Medium	24 / 32	Next to a line of text. The default.
Large	40 / 48	An empty section or a whole view waiting for its content.

Contained

Contained draws the indicator on a raised circle of its own. Use it where the indicator floats over content, as in pull to refresh or over an image or a list, so that it stays visible whatever is behind it. Where it sits on a plain surface, leave it inline.

Show delay and entrance

A wait that ends in a moment should show nothing. So the indicator waits before it is shown: 300 ms in the default system, counted from the moment it is inserted. Then it fades in. A wait shorter than the delay never shows a mark that flashes on and off. During the delay the indicator already takes its full size, so nothing beside it moves when it appears.

Insert the indicator when the wait starts and remove it when the wait ends. The delay counts from insertion: an indicator that is hidden and shown again without being removed does not wait again, and one inserted again waits the whole delay again.

The system decides the delay and the entrance for every indicator. Set them on one indicator only when it needs a different pace:

showDelay is the wait in milliseconds. 0 shows the indicator as it is inserted, for a busy button that should answer the press at once.
entrance is fade or grow. Grow fades the indicator in while it grows from its center. auto, the default, takes the system’s choice.
enterDuration is the entrance’s length in milliseconds. 0 shows the indicator whole at once.

A value you set is used as given: the motion dial does not scale it. Leave a prop unset to take the system’s value.

Do

Give it a label that says what is loading: “Loading messages”, not “Loading”. If a caption is shown next to it, use the same words.
Put it where the content will appear, so the person looks at the right place when it arrives.
When it replaces an icon in a control, keep the control’s size, so nothing around it moves.
Leave the delay to the system unless one indicator needs another pace.

Don’t

Don’t use it for a wait you can measure, or one that may run long. Use a progress indicator.
Don’t show several indicators for one wait. One per region that is loading is enough.
Don’t put it over a whole screen when only one part of it is loading. Keep the rest usable.
Don’t color it to say that something went wrong. Stop it and show a message instead.
Don’t keep an indicator in place and hide it between waits. Remove it, so the next wait starts a new delay.

Accessibility

Role: progressbar
Labeling: label is the accessible name. The indicator has no value: once shown, it is exposed as a progressbar in the platform's busy (indeterminate) state, never as a status message; during its show delay it is not exposed at all (LDG-11).
Minimum target: The hit area meets the minimum target size even when the visual size is smaller. minimum 32px · pointer 44px · spacing 8px · touch 48px

Keyboard

Keys	Action

Notes

Not interactive: the indicator takes no input and is never focusable (LDG-6), so the minimum target holds without extending anything.
comp.loading-indicator.indicator.color must stay at least 3:1 against the surface behind it, and comp.loading-indicator.contained.indicator.color against comp.loading-indicator.contained.container.color (non-text contrast): the moving mark is the only sign that something is happening.
Text size does not change the indicator: it is not text. Where it replaces an icon in a control, the control keeps its size.
A product marks the region it loads as busy (aria-busy on the web) and says when the content has arrived; a wait that may exceed a few seconds, or whose length can be measured, belongs to the progress indicator.
A wait shorter than the show delay shows and exposes nothing (LDG-11): no mark that flashes for a sighted person, and no progressbar that appears and vanishes for a screen-reader user. The product's own busy marking of the region does not wait for the delay; aria-busy and its equivalents announce nothing by themselves.
Reduced motion replaces the turning arc with an opacity pulse of at most one per second (LDG-4), below the three-per-second flash threshold, and turns a grow entrance into a fade (LDG-13). The show delay is kept: it is a wait, not motion (LDG-15).

Generated from specs/loading-indicator.spec.json, tokens/sys/measure.tokens.json

What the component handles

Once shown, it exposes the progress bar role in the platform’s busy state, with the label as its name and no value. Flutter has no progress bar role or busy state yet, so there it exposes the label.
During its show delay it is not in the accessibility tree at all: no role, no name, no busy state. A wait too short to see is not heard either.
It is never focusable, and it does not announce itself when it appears or goes away.
When reduced motion is requested, the arc stops turning and a full circle gently pulses its opacity instead, at most once a second; a container stays still. A grow entrance becomes a fade. The show delay is kept: it is a wait, not motion.
Its animation stops while it cannot be seen — in an app in the background everywhere, and scrolled out of view or on a hidden screen where the platform can tell — and resumes when it can.
An empty label is reported in debug builds.

What you need to do

Mark the region being loaded as busy while it loads (aria-busy on the web), from the start of the wait, without waiting for the indicator’s delay, and say when the content has arrived: a message in a live region, or focus moved to the new content when the person asked for it.
Keep the indicator color at least 3:1 against the surface behind it, and the contained indicator color against its container, if you change them. The moving mark is the only sign that something is happening.

Source code and issues on GitHub