Why Your Loading Spinner Flickers, and the Two Rules That Fix It

Every Flutter application contains a loading spinner, typically represented by a bool variable and a Stack widget. This approach is common, found in tutorials, and correct in principle. However, the implementation often results in a visually unappealing flickering effect on fast networks. This issue arises from the timing of the spinner's appearance and disappearance, not the spinner's design itself.

The primary cause of flickering is the timing of the API call, which typically takes around 90 milliseconds to complete. At 60 frames per second, this equates to approximately five and a half frames. As a result, the spinner mounts, paints for five frames, and then unmounts. To a user, this appears as a flash of grey, an unnoticeable shape that vanishes before their eye can focus on it.

This effect is exacerbated when the timing of the API call is near the boundary of 100 milliseconds. For example, an operation that takes 200ms on Wi-Fi versus 900ms on cellular network connections can produce vastly different user experiences: a flickering screen on the fast network versus a seamless wait on the slow network.

The underlying principle is that showing progress below a certain threshold (around 100ms) can actually be counterproductive. Jakob Nielsen's research highlights a response-time limit of 0.1 seconds for actions to feel instantaneous, and 1 second for uninterrupted thought flow. Below this threshold, displaying progress can disrupt the user's experience more than not displaying it at all. Therefore, a third state is necessary - an intermediate state that indicates progress without being noticeable.

To address this issue, two key rules should be followed. Rule one states that nothing should paint before the reveal delay. Upon initiating an operation, a timer should be started. If the operation completes before the timer fires, no visual feedback should be rendered. This threshold is typically around 140 milliseconds. If the operation completes before this threshold, no spinner or other visual feedback is displayed.

If it exceeds the threshold, the user begins to question whether their tap was registered, and feedback becomes reassuring. This single rule significantly reduces flickering in most applications, as most requests are fast and can go unnoticed.

Rule two is equally crucial but less apparent. When the reveal delay is set to 140ms, and the request finishes at 170ms, the spinner appears for only 30 milliseconds. This replacement of the five-frame flash with a two-frame flash is less desirable. The second rule dictates that once the overlay is committed to appearing, it must remain visible for at least half a second. This ensures the interface appears deliberate rather than glitchy, even if it means waiting slightly longer than strictly necessary.

These two rules form the foundation of the Loading Kit library, which implements these principles to ensure a smoother user experience. The library automatically handles errors and other aspects of loading states, focusing on the critical role of timing in loading indicators.