Loading & Error UI

Two optional files next to a page.jsx give the pages beneath their folder a loading view and an error view.

app/
├─ layout.jsx
├─ error.jsx            # catches failures anywhere in the app
└─ dashboard/
   ├─ layout.jsx
   ├─ loading.jsx       # shown while a dashboard page loads
   ├─ error.jsx         # shown when a dashboard page fails
   ├─ page.jsx
   └─ settings/page.jsx # uses dashboard's loading.jsx and error.jsx

Which file applies

• The nearest one wins. The router looks in the page's folder, then each parent up to app/.

• Inside the layouts. Both replace only the page, so the layouts around it (navbar, sidebar) stay on screen and keep working.

• Layouts use the one above. A broken layout shows the error.jsx above it: see Layout errors.

• Not pages. loading.jsx and error.jsx never become routes of their own.

• JSX or TSX only. A loading.mdx or error.md is a build error.

loading.jsx

// app/dashboard/loading.jsx
export default function Loading() {
  return <DashboardSkeleton />;
}

It shows in two situations:

• While navigating to the page. When the page's loader data or code takes longer than 150 ms, the skeleton replaces the old page inside the layouts. A faster navigation never shows it.

• While the page's resources load. It is the <Pending> fallback for every resource() the page reads outside a section boundary.

It receives { params, query } for the route being loaded.

error.jsx

// app/dashboard/error.jsx
export default function DashboardError({ error, retry }) {
  return (
    <div role="alert">
      <p>Couldn't load the dashboard: {error.message}</p>
      <button onclick={retry}>Try again</button>
    </div>
  );
}

It replaces the page when:

• Without an error.jsx, a failed loader leaves router.data undefined and the page renders, as before.

• notFound() still renders 404.jsx with HTTP 404.

• Redirects and refusals (a thrown Response) are unchanged: see Loader Errors & Redirects.

• Production messages. A server-rendered error page shows "Something went wrong" in production, so a loader's internals never reach the browser. Development shows the real message.

• Static generation. A loader that throws at build time is reported and that page is skipped, as before. An error page is never baked into a static file.

Layout errors

A layout can't show its own error inside itself, because it is the part that broke. Its errors go to the nearest error.jsx above the layout, shown inside the layouts above it.

app/
├─ layout.jsx          # root shell: stays, with its navbar
├─ error.jsx           # shows when the dashboard layout breaks
└─ dashboard/
   ├─ layout.jsx       # throws, or its layout.loader.js fails
   ├─ error.jsx        # only for the dashboard's pages
   └─ page.jsx

• Retry reruns the loaders and rebuilds from the broken layout down.

• The root layout has nothing above it: its errors are reported, not caught. Keep it simple, or wrap risky parts of it in an <ErrorBoundary>.

Dashboards: sections inside the page

The route files are the page-level default. A page whose sections load independently gives each section its own boundary, so they fill in and fail separately:

// app/dashboard/page.jsx
import { Pending } from "@opentf/afw";

export default function Dashboard() {
  return (
    <div class="grid">
      <Pending fallback={<ChartSkeleton />} error={(e, retry) => <SectionError title="Revenue" onRetry={retry} />}>
        <RevenueChart />
      </Pending>
      <Pending fallback={<TableSkeleton />} error={(e, retry) => <SectionError title="Orders" onRetry={retry} />}>
        <RecentOrders />
      </Pending>
    </div>
  );
}

• Each resource waits on its nearest boundary. A section's resources hold that section, not loading.jsx.

• The page shows at once when every section has a boundary: loading.jsx then only covers the navigation and the loader data.

• A section's error shows its failure in place; the other sections keep working.

• Anything no section catches (the loader, the page itself, a section without error) goes to error.jsx.

Compared with other frameworks