One error boundary per widget, not one per page, keeps failures local
Fallback UI shows what broke and a retry button, never a blank screen
Granularity rule: wrap anything that fetches, parses, or renders external data
Reset keys let a boundary recover without a full page reload
A single broken product recommendation widget once blanked my entire storefront homepage. One component threw during render, React unmounted the whole tree, and every visitor saw white. The fix took ten minutes. The lesson took longer. Here is exactly where I put error boundaries now and what I render when things break.
Why One Component Should Never Kill the Whole Page
React has a brutal default. When a component throws during rendering, React unmounts the entire component tree from the root. Not the broken component. The whole thing. If your header, footer, product grid, and cart summary all live under one root and one of them throws, the visitor gets a blank screen.
That is what happened to me. A recommendation widget called an API that returned malformed JSON. The parse threw. React saw an uncaught error at render time and did what it is designed to do: it tore down everything to avoid rendering a corrupted UI. The reasoning is sound. A half-rendered page with inconsistent state can be worse than nothing. But "nothing" is a terrible thing to show a paying customer.
An error boundary is a component that catches errors thrown by its children during rendering, in lifecycle methods, and in constructors. It does not catch errors in event handlers, async code outside render, or server-side rendering. Those need their own handling. But for the render-time throws that unmount your tree, a boundary is the wall that stops the collapse.
The mental model I use: an error boundary is a circuit breaker. When one appliance shorts, you do not want the whole house to go dark. You want the breaker for that one circuit to trip and the rest of the house to stay lit. Each boundary defines a zone. Everything inside the zone can fail together. Everything outside keeps running.
The mistake almost everyone makes, including me for the first year, is putting a single boundary at the app root. That catches everything, which sounds good, but it means any error anywhere blanks the entire app into your one fallback. You traded a white screen for a slightly nicer white screen. The failure is still global. The whole point is to make failures local.
Since I moved to granular boundaries, a broken widget shows a small "could not load" card while the checkout button three inches away still works perfectly. Sales did not stop because a recommendation engine hiccuped. That is the entire value proposition.
The Granularity Rule I Actually Follow
Here is the rule I apply to every page: wrap any component that fetches data, parses external input, or renders content I do not fully control. If a component only renders static markup I wrote by hand, it does not need its own boundary. If it touches the network, a third-party library, or user-generated content, it gets wrapped.
That gives me a clean checklist. My product grid fetches inventory, so it gets a boundary. My reviews section renders user text and star counts from an API, so it gets a boundary. My embedded video player loads a third-party script, so it gets a boundary. My static hero banner with hardcoded copy does not.
I aim for one boundary per independent feature, not one per DOM node and not one per page. Too coarse and a failure takes out a whole region. Too fine and you drown in wrapper components and can never see the forest. The sweet spot is the "feature" level: a widget a user would recognize as a distinct thing. The recommendation carousel is one feature. The cart summary is another. The newsletter signup is a third. Three boundaries, three independent failure zones.
I also nest them deliberately. A page-level boundary catches anything the feature boundaries miss, so a truly unexpected error still lands on a page fallback rather than blanking to root. But the feature boundaries catch first because they are closer to the error. React walks up the tree from the throw point and uses the nearest boundary. So the carousel boundary catches the carousel error before the page boundary ever sees it.
One number that made this concrete: on my busiest page I have seven feature boundaries. In the six months since I added them, four of those zones have tripped at least once in production due to flaky third-party APIs. Every single time, the rest of the page kept working. Before boundaries, each of those four incidents would have been a full outage on that page.
If you want the deeper context on how I structure a full build like this, see Claude Blueprint, which walks through my whole component setup.
What Goes in the Fallback UI
A fallback is not an error page. It is a placeholder for one broken zone, so it should look like it belongs on the page. My rule: the fallback occupies roughly the same space the working component would, so the layout does not jump when a widget fails.
I put three things in every fallback. First, a plain sentence saying what could not load, in human language. Not "Error: undefined is not a function." Something like "Recommendations could not load right now." The visitor should never see a stack trace. Second, a retry button when a retry makes sense. Most of my failures are transient network issues, so a retry that re-mounts the component fixes it more than half the time. Third, nothing else. No apology paragraph, no support links, no drama. A small card, a message, a button.
For a failed product image I render a neutral gray box the exact dimensions of the image. For a failed reviews section I render a compact line: "Reviews are temporarily unavailable." For a failed checkout-adjacent widget I am more careful, because that is where sales happen, so the fallback explicitly says the rest of checkout still works.
I log every fallback render. When a boundary catches an error I fire it off to my logging service with the component name, the error message, and the current URL. This is the part people skip. A boundary that silently swallows errors means you never find out your recommendation widget has been broken for three weeks. The boundary protects the user experience, and the log protects you. I check that log weekly and it has caught two bugs that produced no visible symptom because the fallback looked fine.
One thing I do not do: I never put important content behind a boundary that hides it on failure. If a component shows the actual price, its fallback cannot just say "price unavailable" and move on, because that costs a sale. For those I fetch the critical data at a higher level where it is more stable and only wrap the enhancement layer. The boundary protects the nice-to-have, never the must-have.
Resetting a Boundary Without Reloading the Page
The hardest part is recovery. Once a boundary catches an error and renders the fallback, it stays in the fallback state. It does not automatically try again, because if it re-rendered the same broken children it would just throw again and loop. So by default a tripped boundary is stuck until the whole page reloads. That is a bad experience.
The clean fix is a reset key. I give the boundary a key value tied to something that changes when a retry should happen. When that key changes, the boundary resets its internal error state and re-renders its children fresh. My retry button increments a counter in state, that counter feeds the boundary as a reset key, and clicking it gives the broken component a clean second attempt without touching the rest of the page.
I also reset on route change. When a visitor navigates to a new product, the URL becomes part of the reset key, so a boundary that tripped on the previous product starts fresh on the new one. Without this, a single bad product could poison a widget for the entire session even after the visitor moved on.
The subtle trap is the retry loop. If the underlying cause is not transient, a visitor who mashes retry just re-triggers the same throw over and over, each time logging another error and burning API calls. I cap it. After three retries the boundary shows a final state with no retry button: "This could not load. Try again later." That protects my logs from spam and my APIs from a hammering when something is genuinely down.
I tested this with a deliberately broken endpoint. Killed the API, watched the boundary trip, clicked retry, saw the same fallback, clicked twice more, and on the fourth attempt the retry button was gone and the final message stood. Restored the API, changed the product, and the new route reset everything to a clean load. The rest of the page never flickered once through any of it.
The whole recovery story is what turns error boundaries from a defensive crash guard into something a visitor barely notices. A widget blinks, shows a card, and either recovers on retry or fails quietly while everything around it keeps selling.
Bottom Line
Error boundaries are not about hiding errors. They are about containing them. One broken widget should cost you one widget, never the whole page and never a sale. The three rules that matter: place a boundary around anything that fetches, parses, or renders data you do not control; render a fallback that fits the layout, says what broke in plain words, and offers a capped retry; and reset the boundary on retry or route change so recovery does not need a full reload.
I moved from one root boundary to seven feature boundaries on my busiest page, and four production failures since then stayed local instead of going global. That is the entire payoff. The frontend feels sturdier because failures no longer cascade.
If you are building out a storefront on Shopify with custom React sections, this pattern pays for itself the first time a third-party script goes down mid-sale. For the wider picture on how I structure these builds, Claude Blueprint has the full setup. Start with your riskiest widget and wrap that first.
This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)
Top comments (0)