Analogies for thinking & teaching Suspense?

[Skn0tt]

Blitz.js promoted Suspense since inception, and I've found the following analogy to be quite helpful for explaining what it does and why that's useful:

Imagine a component that needs to do some asynchronous task before it can render, e.g. fetching some data.

Before Suspense, such a component would keep an isLoading state and return some kind fallback (an empty state, skeleton, spinner, ...) based on it.

With Suspense, a component can now, during rendering, shout "HALT! I'm not ready yet. Don't continue rendering me, please - here's a pager, I'll ping you when I'm ready!¹"
React will walk up the tree to find the nearest Suspense boundary, which is set by You and contains the fallback that'll now be rendered until the pager is ringing.

I'd then continue to talk about how Suspense allows you to colocate data fetching with presentation, programming as if all data were already available, and realising somewhat complex fallback orchestration.

I like this analogy b/c I found that the personification is fun and easier to grasp. I'm curious, which analogies do y'all use to explain Suspense to students / coworkers?

---

¹ the pager example can be replaced with a Promise, depending on who you're talking to

[gaearon]

This is nice way to explain it.

Don't continue rendering me, please - here's a pager, I'll ping you when I'm ready!"

I'm not sure if this is an intentional detail, but it's pretty accurate as to how Suspense works internally — we even literally call these wake-up calls "pings" in the source code:

https://github.com/facebook/react/blob/0e100ed00fb52cfd107db1d1081ef18fe4b9167f/packages/react-reconciler/src/ReactFiberThrow.new.js#L161-L190

Another way I like to explain it is that it's like throw / catch but for loading states. When a component says "I'm not ready" (exceptional situation, like throw), the closest Suspense block above (like catch) shows the fallback instead. Then, when the Promise resolves, we "retry" rendering.

One key difference with traditional Promise-based programming is that Promises are not exposed to the user code. You don't deal with them directly. You don't Promise.all them or .then them or anything like this. Instead of "wait for Promise to resolve and run some user code", the paradigm is "React will retry rendering when it resolves". In some ways it's simpler but it takes some "unlearning" because the user loses some control they might be used to from traditional Promise-base programming.

programming as if all data were already available

This is very on-point and is also how we like to explain it.

[rickhanlonii]

I think this is great. One thing I've started to appreciate with Suspense that sometimes get lost when we talk about the ability to just express fallbacks in Suspense is how much this opens up the ability for React to coordinate or make decisions for data dependencies. Note: we may not do all of these examples yet, but it helps explain abilities that we have with the Suspense model.

For example, say there are multiple components that suspend within a boundary. React knows there are multiple, so it can render each subtree as they're ready, but wait until all of the data is available and rendered before committing. Here, this is like React waiting for all of the pages in a boundary before rendering anything.

Or another example - say there are multiple suspense boundaries in a tree and the data for each comes in around the same time (<100ms). If you paged one, committed it, then paged the other, and committed it, then you'd see a bit of jank. The ideal is that we would wait and commit both if they're ready around the same time. This is like React waiting for all the pages it gets in some small ms window before rendering.

Or another - say you've already rendered content and you want to refresh it. But you want the content that's already there to stay in place and interactive while the data is refreshing. In this case, you don't want to regress to a placeholder, you want to infinitely wait and then swap the new content in. This is like when you give React the pager, it just keeps what you have until you tell it the new content is ready, and swaps that in.

A final example - say you're server-side rendering and the component suspends. Then ideally React will start sending what it's rendered to the client while you're waiting for the results of what suspended. Then, when that's available, it sends that to the client. That means when you page React to tell it the results are ready, React will render it and send it to the client.

So, as you can see it's much more than just allowing you to render placeholders in an API ergonomic way. If it was just that, then it wouldn't too much of an improvement over user implementations. Suspense gives you the ability to tell React what your data dependencies are so it can coordinate rendering based on the data you need.

[Skn0tt]

Thank you for expanding to these examples!

Sometimes, I find myself talking about how "giving control to your framework / language" is great for A. Conventions and B. Free, Continuous Improvement. I'd also list Suspense as an example, and your examples are great to elaborate on that!

[sylwiavargas]

This is a very helpful thread! Thank you 💕