Building a Polyfill for React Suspense

The best way to understand a software concept is to try and build it yourself.?—?TB

If you love React, you’ve probably heard something about the upcoming Suspense APIs, but even after watching a demo or two, it was pretty difficult for me to lay my finger on how exactly Suspense works.

So I put my computer science cap on and decided to try and recreate it with the current version of React v16.

A few disclaimers before we get started that my fictional legal team wants to get out of the way.

The actual version of Suspense that will ship with React is significantly more complicated and efficient than the version in this polyfill. This tutorial & accompanying module are meant mainly for learning and experimental purposes. Also, the current polyfill will likely not play well with SSR.

Hic Draconis!

If you only care about the codes, check out

react-suspense-polyfill, otherwise here we go!

Setting the Stage

IMHO, Suspense is a very powerful addition to the core React API surface, and I believe it will have a profound effect on how pragmatic React code is written a few years from now.

If you take nothing else away from this article, understand this:

At its core, React Suspense works by allowing an async component to throw a Promise from its render method.

This polyfill mimics React’s internal support for this behavior by implementing an error boundary in the Timeout component. If the error boundary encounters a thrown Promise, it waits until that Promise resolves and then attempts to re-render its children. It also handles falling back to loading content if the Promise takes too long to resolve. (explained in detail below)

I hope this module and accompanying demos make it easier to get up-to-speed with React Suspense. ?


Placeholder is the main public-facing component exposed by React Suspense. Its interface is relatively straightforward, exposing the following props:

  • delayMs – Amount of time in milliseconds to wait before displaying fallback / loading content. The main reason for adding a delay before displaying fallback content is to prevent loading indicators flashing too quickly before the main async content loads which can be an annoying UI distraction.
  • fallback – A React Node that will be displayed while any child component is loading only after delayMs have elapsed. This will typically be some type of loading spinner.
  • suspense – A React Node that will be displayed while any child component is loading only before delayMs have elapsed. Note: this optional prop is specific to react-suspense-polyfill and is strictly for the purpose of demoing how suspense works.
  • children – A React Node that represents the main content of this Placeholder component which may or may not throw a Promise while loading asynchronous resources. See react-async-elements for some examples of super sexy, async-friendly child components.

Placeholder is the component you’re most likely to use in your code, but in the spirit of understanding how it works, the majority of the complexity is handled by Timeout.


The Timeout component is a bit more tricky, so let’s break down what’s going on in steps:

  1. The render method (Line 50) will initially invoke its children render function with a boolean value signifying whether or not this component has hit its timeout ms since mounting and encountering an async workload.
  2. If the children render successfully, all is well with the world and React continues on as normal. ?
  3. If any component within the children subtree throws a Promise from its render method, it will be caught by Timeout’s error boundary, componentDidCatch (Line 24).
  4. The error handler first starts a timeout for this async work (Line 28), such that the Timeout will fall back to displaying loading content if & when the ms timeout expires.
  5. During the ms time before this Promise may expire, the Timeout is “in suspense” (Lines 29 and 63), which essentially means that we’re waiting for some resource to load but it hasn’t taken long enough to justify displaying the fallback / loading content just yet.
  6. Once the Promise resolves (Line 43), Timeout once again invokes its children render prop (Line 39) with the expectation that this time, the initial asynchronous resource will resolve synchronously and all will once again be well with the world. ?

Note that it’s entirely possible for a subtree to contain multiple, independent async resources, in which case the Timeout component may repeat steps 3–6 once for each async resource that needs to be resolved. Alternatively, Placeholders & Timeouts may be nested like any React component, so it’s entirely possible that a higher-level Timeout won’t need to handle an async request that is thrown lower in the React component tree if that request is captured by a Timeout closer to its origin. This follows the public behavior of React error boundaries pretty closely.

Hopefully, the Placeholder and underlying Timeout components are now more concrete in terms of how they’re expected to behave.

99% of the time you’ll be working with a simple Placeholder component and ignoring these details in Timeout, but I believe it’s extremely beneficial and empowering to have this type of deeper mental model to rely on for the type of fundamentally game-changing pattern that React Suspense supports.

And with that in mind, let’s talk a bit about how this basic mental model differs from the official version that the extremely talented React core team is cooking up!

Comparison to Official React Suspense

There are two major limitations of this polyfill compared with the forthcoming official implementation of React Suspense.


Okay, so we may have cheated a little bit ? There is one important detail that we left out of our implementation in terms of polyfilling the correct behavior.

Can you guess what it is?

If you’re not sure, that’s completely fine. I had done this whole coding exercise before I realized that Dan Abramov had pointed out a potential flaw with this approach, so don’t worry if you’re drawing a blank…

Spread the love

Posted by News Monkey