loading.js and error.js in Next.js: Clean Loading and Error States

TL;DR — Drop a loading.js next to any page for an automatic skeleton and an error.js client component with a reset retry button; wrap slow sections in Suspense for finer control.

The core idea

In the App Router, a loading.js file next to any page.js renders automatically while data loads, and an error.js file shows a proper message with a retry button instead of a white screen when something breaks. No manual setTimeout, no isLoading flags scattered across components.

One catch: loading.js only kicks in when the page is genuinely async (a fetch or dynamic data). Static pages render instantly, so no loading state appears — that's expected.

Skeleton loading with loading.js

A skeleton that mimics the real page shape; users feel progress instead of a freeze:

// app/shop/loading.tsx
export default function Loading() {
  return (
    <div className="grid gap-4">
      {[1, 2, 3].map((i) => (
        <div key={i} className="h-24 animate-pulse rounded bg-gray-200" />
      ))}
    </div>
  );
}

To avoid blocking the whole page, wrap only the slow part in Suspense so the rest renders immediately (streaming). This pairs nicely with image optimization since images are usually the slowest part:

Graceful errors with error.js

The error file must be a client component ("use client") receiving two props: the error itself and a reset function for retrying:

Don't forget to log errors (Sentry or whatever you use). error.js only catches its nearest parent segment, so header and footer stay in place while the middle shows the message. A crash in the root layout needs global-error.js instead.

Quick comparison

| Approach | Good for | Bad for | |---|---|---| | loading.js | Whole-segment loading, zero extra code | Blocks the whole segment | | Suspense around slow parts | Real streaming, better UX | Slightly more code | | error.js + reset | Scoped errors plus retry | Only render/data errors in that segment | | Manual try/catch | Per-action custom logic | Repeated boilerplate everywhere |

Rule of thumb: loading.js to start, Suspense for key sales pages, error.js everywhere.

Checklist

• [x] Every data-driven route has a loading.js shaped like the page
• [x] error.js is a client component with a reset retry button
• [x] Errors get logged, not just displayed
• [ ] Slow sections of key pages split with Suspense (e.g. product lists)
• [ ] Error behavior tested manually once (e.g. kill the API)
• [ ] If you have auth, cross-check with the middleware auth guide so login redirects don't clash with error boundaries

FAQ

Q: Why doesn't my loading.js show?

Because your page renders statically. Without a dynamic fetch or a real await, the page is ready instantly and there's nothing to show. Test with Suspense around an async component.

Q: What exactly does reset do?

It re-renders the failed segment without a full page refresh. Transient failures (API hiccup) recover; permanent ones show the error again.

Q: What doesn't error.js catch?

Root-layout errors and server errors outside rendering (like middleware). Use global-error.js for the former and handle the latter separately.

Sources

• loading.js reference in the Next.js docs — official skeleton behavior with Suspense
• error.js reference in the Next.js docs — the client-component requirement and the reset parameter
• not-found.js reference in the Next.js docs — the companion for invalid routes
• Stack Overflow: loading or Suspense fallback won't show in production — why the fallback disappears in a final build
• Suspense reference in the React docs — fallback behavior and the boundaries both files rely on