Boundaries
With one boundary around a whole product page, a slow recommendations query keeps the product behind a spinner, and one failed request takes the whole page down. With no boundary at all, an unhandled error halts the reactive system and nothing on the page updates again. Boundaries decide how much of the page a loading or failed read affects:
Loadingshows a fallback while async data in its subtree has not loaded yet.Erroredshows a fallback when its subtree throws.Revealdecides the order in which sibling regions appear.
This page is about where to put each one.
import { Errored, Loading, createMemo, createSignal } from "solid-js";
type Product = { id: string; name: string; description: string };
async function fetchProduct(id: string): Promise<Product> { const response = await fetch(`/api/products/${id}`); if (!response.ok) throw new Error(`Could not load product ${id}`); return response.json();}
function ProductPanel() { const [productId, setProductId] = createSignal("mug"); const product = createMemo(() => fetchProduct(productId()));
return ( <> <ProductPicker value={productId()} onSelect={setProductId} /> <Errored fallback={(error, reset) => ( <section> <p>{String(error())}</p> <button onClick={reset}>Retry</button> </section> )} > <Loading on={productId()} fallback={<p>Loading product…</p>}> <h2>{product().name}</h2> <p>{product().description}</p> </Loading> </Errored> </> );}On first render the panel shows "Loading product…" and the picker is usable. When the request resolves the product appears; when it rejects, the error message and a Retry button appear in the same place. Pick another product and the panel shows the loading text again while the picker keeps working.
Three rules explain that behavior:
- The nearest boundary above a read handles it.
- Loading and errors are separate:
Loadingdoes not hide an error, andErroreddoes not show loading UI. Both can wrap the same region. - Anything outside a boundary stays on screen, so the picker is always usable.
Loading boundaries
Loading shows its fallback until the async values read inside it have loaded for the first time.
After that, it keeps the content on screen during updates and replaces it when the new content is ready, as Async reactivity explains.
Use isPending in the content to show that an update is loading.
Place a boundary around the smallest region its fallback should replace, and leave controls the user needs during the load outside it:
// Avoid: one boundary around the page, so a slow query hides everything<Loading fallback={<PageSkeleton />}> <ProductPicker value={productId()} onSelect={setProductId} /> <ProductDetail id={productId()} /> <Recommendations id={productId()} /></Loading>
// Prefer: one boundary per region that should have its own fallback<ProductPicker value={productId()} onSelect={setProductId} /><Loading fallback={<DetailSkeleton />}> <ProductDetail id={productId()} /></Loading><Loading fallback={<CardSkeleton />}> <Recommendations id={productId()} /></Loading>In the Avoid version, the picker is gone until the slower of the two requests finishes.
In the Prefer version the picker is always there, the detail pane appears when the product arrives, and the recommendations appear when they do.
The on prop says which changes should bring the fallback back.
Without it, choosing a new product keeps the old product on screen while the new one loads.
With on={productId()}, changing the id shows the skeleton while the new product loads.
Pass several inputs as an array, on={[productId(), variant()]}.
Anything on does not read, such as a refresh of the same product, leaves the content in place.
The fallback appears together with the rest of the update.
If other content outside the boundary is waiting on the same change, the skeleton appears when that content is ready.
If the same data is also read outside the boundary, the fallback never appears, and development warns LOADING_ON_OUTSIDE_HOLD.
Move that read inside the boundary to fix it.
Async reactivity shows each case.
on is tracked, so the expression has to read the signal; an accessor that is never called reads nothing.
// Avoid: nothing is read, so no change ever re-arms the boundary<Loading on={productId} fallback={<DetailSkeleton />}>
// Prefer: read the value<Loading on={productId()} fallback={<DetailSkeleton />}>With the uncalled accessor, picking another product keeps the old product on screen for the whole load, as if on were not there.
Error boundaries
Errored catches an error thrown in its subtree, including a rejected request, and shows its fallback instead of the content.
Content outside the boundary stays on screen.
Place it around the smallest region that can fail and recover as one unit. For the product page, that is the detail pane and the recommendations separately: a failed recommendations query should not take the product with it.
The fallback can be an element or a function.
The function receives an accessor for the error and a reset function that retries what failed.
Recovery
An errored region does not need reset to recover.
The error clears as soon as the failed data produces a value again:
- An input of the failed computation changes. In the example above, picking another product after a failed request runs the fetch for the new id, and the content returns if that request succeeds.
- A
refresh(source)succeeds. - A
liveserver function reconnects and yields a value.
reset is for when nothing else will change on its own, such as after a network outage.
A retry that fails again shows the fallback again, and a retry that succeeds shows the content.
While the retry runs, the error fallback stays on screen.
In the product panel above, clicking Retry leaves the error message in place until the request finishes; the Loading inside Errored does not show "Loading product…".
To show the placeholder during a retry, move Loading outside Errored and give it an on value that the retry changes:
const [productId, setProductId] = createSignal("mug");const [attempt, setAttempt] = createSignal(0);const product = createMemo(() => fetchProduct(productId()));
<Loading on={[productId(), attempt()]} fallback={<p>Loading product…</p>}> <Errored fallback={(error, reset) => ( <section> <p>{String(error())}</p> <button onClick={() => { setAttempt((n) => n + 1); reset(); }} > Retry </button> </section> )} > <h2>{product().name}</h2> <p>{product().description}</p> </Errored></Loading>;Click Retry and "Loading product…" replaces the error message until the request finishes; then the product or a new error message appears.
Changing attempt is what brings the fallback back (see Show a placeholder again).
Without on, the outer Loading also keeps the error message on screen, because the region already has content.
An error thrown while rendering an Errored fallback is not caught by that boundary.
A parent Errored can catch it.
With no boundary above, an unhandled error halts the reactive system, which development reports as [REACTIVITY_HALTED]; Debugging reactivity covers that report.
Reveal order
Independent loading regions appear in the order their data arrives. On a product page with a detail pane, reviews, and recommendations, fast recommendations can pop in below the detail skeleton, and the layout shifts as each region appears. Server rendering has the same problem in the HTML stream, where fragments arrive out of order.
Reveal controls when the Loading boundaries directly inside it show their content.
It does not fetch data or delay requests; it only decides when ready content appears:
import { Loading, Reveal } from "solid-js";
<Reveal collapsed> <Loading fallback={<DetailSkeleton />}> <ProductDetail id={productId()} /> </Loading> <Loading fallback={<CardSkeleton />}> <Reviews id={productId()} /> </Loading> <Loading fallback={<CardSkeleton />}> <Recommendations id={productId()} /> </Loading></Reveal>;The recommendations can finish first and still wait their turn behind the detail pane and the reviews.
collapsed keeps the skeletons after the current one from stacking below it, so only one skeleton is visible at a time.
The three orders:
sequential, the default, shows regions in order; a region stays on its fallback until every region before it is ready.togetherwaits until every region is ready, then shows them all at once.naturalshows each region as soon as its own data loads. On its own this is the same as noReveal; it is useful nested inside anotherReveal, where the whole group takes one place in the outer order.
function ProductPage() { return ( <Reveal> <Loading fallback={<DetailSkeleton />}> <ProductDetail id={productId()} /> </Loading> <Reveal order="natural"> <Loading fallback={<CardSkeleton />}> <Reviews id={productId()} /> </Loading> <Loading fallback={<CardSkeleton />}> <Recommendations id={productId()} /> </Loading> </Reveal> <Loading fallback={<FooterSkeleton />}> <RelatedProducts id={productId()} /> </Loading> </Reveal> );}The detail pane appears first. Then reviews and recommendations appear independently, in whichever order they load. The related products wait until both of those are shown.
Deep diveWhich boundaries join a reveal group
A Loading boundary joins the nearest Reveal above it when it is created.
A Loading nested inside another Loading does not join the outer group, and a Loading wrapped in Errored does not delay the group above it.
A nested Reveal joins its parent group as one region.
Its boundaries stay on their fallbacks until the parent group reaches it, and then the nested group follows its own order.
Wrapping a region in another Loading does not take it out of an outer Reveal.
Move the region outside the outer Reveal when it should appear on its own.
Primitive forms
The components above are built from three primitives, createLoadingBoundary, createErrorBoundary, and createRevealOrder.
They are exported from solid-js, but their types are in solid-js/internal, which has no semver guarantee.
They exist for renderer integrations.
In application code, build a custom boundary from Loading, Errored, and Reveal:
import { Errored, Loading } from "solid-js";import type { JSX } from "@solidjs/web";
function StatusBoundary(props: { children: JSX.Element; loading: JSX.Element;}) { return ( <Errored fallback={(error, reset) => ( <section> <p>{String(error())}</p> <button onClick={reset}>Retry</button> </section> )} > <Loading fallback={props.loading}>{props.children}</Loading> </Errored> );}Common problems
The whole page shows a skeleton while one region loads
The Loading boundary is above the region that is slow.
Move the boundary down to the region whose fallback should show, and leave the rest of the page outside it.
The request can stay where it was; the Async reactivity page explains why the fetch and the boundary are placed independently.
Choosing a new item keeps the old one on screen
That is the default: after the first load, the boundary keeps its content during updates.
Add on={id()} to the boundary when a change of subject should show the fallback, and read the signal inside it rather than passing the accessor.
If on is already there and the old item still stays, check the console.
LOADING_ON_OUTSIDE_HOLD means the same data is also read outside the boundary, such as a title showing the item's name.
Move that read inside the boundary.
Without the warning, other content that reads the same input is holding the update, such as a sibling boundary without on.
The skeleton appears when that content is ready, or not at all if this item loads first.
Give the sibling its own on, or drop on and show the wait with isPending.
Retry shows the same error
reset re-runs the failed sources with the same inputs.
If the cause has not changed, the same error comes back.
When the fix is a different input, change the input; the boundary recovers on its own.
Retry keeps showing the error instead of a loading state
An Errored boundary keeps its fallback while a reset retry runs, so a Loading inside it cannot show its fallback.
Put Loading outside Errored and add a value that the Retry button changes to its on, as in Recovery.
A region inside Reveal does not appear when its data is ready
The region is in a sequential group and an earlier region is not ready.
Give the group order="natural", wrap the independent regions in a nested <Reveal order="natural">, or move the region outside the group.
Recap
- Put
Loadingaround the smallest region its fallback should replace, and keep the controls the user needs outside it. - Put
Erroredaround the smallest region that can fail and recover as a unit; both boundaries can wrap the same region. - After the first load,
Loadingkeeps its content during updates; addon={key()}when a changed subject should show the fallback again. Call the signal insideon, and keep every read of that data inside the boundary. - An errored region recovers when an input changes or a refresh succeeds;
resetis for when nothing upstream will change. - An error thrown by a fallback needs a boundary above it.
- Use
Revealto control the order sibling regions appear in. - Nest
<Reveal order="natural">to let a group of regions take one place in an outer order.
Next steps
- Rendering and SSR: how
Loadingboundaries decide what goes in the initial HTML shell and what streams later. - Mutations: which errors an
actionshould catch itself and which should reachErrored. - Server functions: reads and live sources whose errors and reconnects these boundaries handle.
- Solid Router: where to put the
Loadingboundary aroundprops.childrenso the first page load has a fallback, and why a later navigation keeps the current page without one.