Learning Objectives

Error boundaries with error.tsx
Loading states with loading.tsx
Suspense for streaming
Not found handling
Global error handling

1. Loading States

Loading states provide visual feedback while content is being fetched. They prevent blank screens and improve perceived performance by showing users that something is happening.

loading.tsx

Next.js automatically wraps your page in a Suspense boundary when you create a loading.tsx file. This component displays immediately while the page content loads, creating a smooth transition.

// app/(dashboard)/transactions/loading.tsx
export default function TransactionsLoading() {
  return (
    <div className="space-y-4">
      {/* Header skeleton */}
      <div className="h-8 w-48 bg-gray-200 animate-pulse rounded" />

      {/* Filter skeleton */}
      <div className="flex gap-2">
        {[...Array(4)].map((_, i) => (
          <div
            key={i}
            className="h-10 w-24 bg-gray-200 animate-pulse rounded"
          />
        ))}
      </div>

      {/* List skeleton */}
      <div className="space-y-3">
        {[...Array(5)].map((_, i) => (
          <div key={i} className="h-20 bg-gray-200 animate-pulse rounded-lg" />
        ))}
      </div>
    </div>
  );
}

Skeleton Components

Skeleton components are reusable loading placeholders that mimic the shape of the actual content. They use the animate-pulse class for a subtle breathing animation that indicates loading.

// components/skeletons.tsx
export function CardSkeleton() {
  return (
    <div className="p-6 bg-white rounded-lg shadow animate-pulse">
      <div className="h-4 w-24 bg-gray-200 rounded mb-2" />
      <div className="h-8 w-32 bg-gray-200 rounded" />
    </div>
  );
}

export function TransactionSkeleton() {
  return (
    <div className="flex items-center justify-between p-4 bg-white rounded-lg shadow animate-pulse">
      <div className="flex items-center gap-4">
        <div className="w-10 h-10 bg-gray-200 rounded-full" />
        <div>
          <div className="h-4 w-24 bg-gray-200 rounded mb-2" />
          <div className="h-3 w-16 bg-gray-200 rounded" />
        </div>
      </div>
      <div className="text-right">
        <div className="h-4 w-20 bg-gray-200 rounded mb-2" />
        <div className="h-3 w-16 bg-gray-200 rounded" />
      </div>
    </div>
  );
}

export function TableSkeleton({ rows = 5 }: { rows?: number }) {
  return (
    <div className="bg-white rounded-lg shadow overflow-hidden">
      {/* Header */}
      <div className="bg-gray-50 px-6 py-3 flex gap-4">
        <div className="h-4 w-20 bg-gray-200 rounded" />
        <div className="h-4 w-32 bg-gray-200 rounded" />
        <div className="h-4 w-24 bg-gray-200 rounded" />
        <div className="h-4 w-20 bg-gray-200 rounded" />
      </div>
      {/* Rows */}
      {[...Array(rows)].map((_, i) => (
        <div key={i} className="px-6 py-4 border-t flex gap-4 animate-pulse">
          <div className="h-4 w-20 bg-gray-200 rounded" />
          <div className="h-4 w-32 bg-gray-200 rounded" />
          <div className="h-4 w-24 bg-gray-200 rounded" />
          <div className="h-4 w-20 bg-gray-200 rounded" />
        </div>
      ))}
    </div>
  );
}

2. Suspense for Streaming

Suspense enables streaming, allowing different parts of the page to load independently. Fast content appears immediately while slower content displays its fallback until ready.

This approach improves time-to-first-byte and allows users to start interacting with parts of the page while other sections are still loading.

// app/(dashboard)/dashboard/page.tsx
import { Suspense } from "react";
import WalletCard from "@/components/dashboard/WalletCard";
import TransactionList from "@/components/dashboard/TransactionList";
import QuickStats from "@/components/dashboard/QuickStats";
import { CardSkeleton, TransactionSkeleton } from "@/components/skeletons";

export default function DashboardPage() {
  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-bold">Dashboard</h1>

      {/* Wallet loads first */}
      <Suspense fallback={<CardSkeleton />}>
        <WalletCard />
      </Suspense>

      {/* Stats can load independently */}
      <Suspense
        fallback={
          <div className="grid grid-cols-3 gap-4">
            <CardSkeleton />
            <CardSkeleton />
            <CardSkeleton />
          </div>
        }
      >
        <QuickStats />
      </Suspense>

      {/* Transactions load last */}
      <Suspense
        fallback={
          <div className="space-y-3">
            {[...Array(3)].map((_, i) => (
              <TransactionSkeleton key={i} />
            ))}
          </div>
        }
      >
        <TransactionList />
      </Suspense>
    </div>
  );
}

Async Components with Suspense

Server Components can be async and fetch data directly. When wrapped in Suspense, they stream their content to the client as soon as the data is ready.

// components/dashboard/WalletCard.tsx
async function WalletCard() {
  // This fetch happens on the server
  const wallet = await getWallet();

  return (
    <div className="p-6 bg-gradient-to-r from-primary to-primary-dark text-white rounded-lg shadow">
      <p className="text-sm opacity-80">Wallet Balance</p>
      <p className="text-3xl font-bold">₦{wallet.balance.toLocaleString()}</p>
    </div>
  );
}

3. Error Handling

Error handling prevents your application from crashing when something goes wrong. The error.tsx file creates an error boundary that catches errors and displays a fallback UI.

error.tsx

Error components must be Client Components because they use hooks. They receive the error object and a reset function to retry rendering. The useEffect hook can log errors to a monitoring service.

// app/(dashboard)/transactions/error.tsx
"use client";

import { useEffect } from "react";

interface ErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function TransactionsError({ error, reset }: ErrorProps) {
  useEffect(() => {
    // Log error to error reporting service
    console.error("Transactions page error:", error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-[400px] p-8">
      <div className="text-6xl mb-4">😕</div>
      <h2 className="text-xl font-bold text-gray-900 mb-2">
        Something went wrong
      </h2>
      <p className="text-gray-600 mb-6 text-center max-w-md">
        We couldn't load your transactions. This might be a temporary issue.
      </p>
      <div className="flex gap-4">
        <button
          onClick={reset}
          className="px-6 py-2 bg-primary text-white rounded-lg hover:bg-primary-dark"
        >
          Try again
        </button>
        <a
          href="/dashboard"
          className="px-6 py-2 border border-gray-300 rounded-lg hover:bg-gray-50"
        >
          Go to Dashboard
        </a>
      </div>
      {error.digest && (
        <p className="mt-4 text-sm text-gray-400">Error ID: {error.digest}</p>
      )}
    </div>
  );
}

Global Error Handler

The global-error.tsx file handles errors in the root layout. It must include its own html and body tags since it replaces the entire page when an error occurs at the root level.

// app/global-error.tsx
"use client";

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <div className="min-h-screen flex items-center justify-center bg-gray-50">
          <div className="text-center p-8">
            <h1 className="text-4xl font-bold text-gray-900 mb-4">
              Oops! Something went wrong
            </h1>
            <p className="text-gray-600 mb-6">
              We're experiencing technical difficulties. Please try again.
            </p>
            <button
              onClick={reset}
              className="px-6 py-3 bg-primary text-white rounded-lg"
            >
              Reload Page
            </button>
          </div>
        </div>
      </body>
    </html>
  );
}

4. Not Found Handling

Not found pages display when a requested resource does not exist. You can create a global 404 page or route-specific not-found pages for more contextual messaging.

Global not-found.tsx

This global not-found page displays for any route that does not match a defined page. It provides navigation options to help users find their way.

// app/not-found.tsx
import Link from "next/link";

export default function NotFound() {
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="text-center">
        <h1 className="text-9xl font-bold text-gray-200">404</h1>
        <h2 className="text-2xl font-bold text-gray-900 mt-4">
          Page Not Found
        </h2>
        <p className="text-gray-600 mt-2 mb-8">
          The page you're looking for doesn't exist or has been moved.
        </p>
        <div className="flex gap-4 justify-center">
          <Link
            href="/"
            className="px-6 py-3 bg-primary text-white rounded-lg hover:bg-primary-dark"
          >
            Go Home
          </Link>
          <Link
            href="/dashboard"
            className="px-6 py-3 border border-gray-300 rounded-lg hover:bg-gray-50"
          >
            Dashboard
          </Link>
        </div>
      </div>
    </div>
  );
}

Route-Specific Not Found

For dynamic routes, call the notFound function when a resource is not found. This triggers the nearest not-found.tsx page, which can be customized for that route segment.

// app/(dashboard)/transactions/[id]/page.tsx
import { notFound } from "next/navigation";

export default async function TransactionPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const transaction = await getTransaction(id);

  if (!transaction) {
    notFound();
  }

  return <TransactionDetails transaction={transaction} />;
}

Create a route-specific not-found page to provide contextual messaging. This file lives alongside the page and displays when notFound is called from that route.

// app/(dashboard)/transactions/[id]/not-found.tsx
import Link from "next/link";

export default function TransactionNotFound() {
  return (
    <div className="text-center py-12">
      <h2 className="text-xl font-bold mb-2">Transaction Not Found</h2>
      <p className="text-gray-600 mb-6">
        This transaction doesn't exist or you don't have access to it.
      </p>
      <Link
        href="/transactions"
        className="px-6 py-2 bg-primary text-white rounded-lg"
      >
        View All Transactions
      </Link>
    </div>
  );
}

5. Error Boundary Component

For more granular error handling within a page, create a reusable ErrorBoundary component. This allows you to wrap specific sections and handle errors without affecting the entire page.

This class component catches JavaScript errors anywhere in its child component tree. It logs errors and displays a fallback UI that can be customized via props.

// components/ErrorBoundary.tsx
"use client";

import { Component, ReactNode } from "react";

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
  error?: Error;
}

export default class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error("ErrorBoundary caught:", error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return (
        this.props.fallback || (
          <div className="p-4 bg-red-50 text-red-600 rounded-lg">
            <p className="font-medium">Something went wrong</p>
            <button
              onClick={() => this.setState({ hasError: false })}
              className="text-sm underline mt-2"
            >
              Try again
            </button>
          </div>
        )
      );
    }

    return this.props.children;
  }
}

6. Loading States for Actions

Beyond page loading, you need to show feedback during user actions like form submissions and data refreshes. React provides hooks specifically for these scenarios.

Form Loading States

The useFormStatus hook provides the pending state of the parent form. Create a submit button component that shows a spinner during form submission.

"use client";

import { useFormStatus } from "react-dom";

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="relative w-full py-3 bg-primary text-white rounded-lg disabled:opacity-70"
    >
      {pending && (
        <span className="absolute inset-0 flex items-center justify-center">
          <Spinner />
        </span>
      )}
      <span className={pending ? "invisible" : ""}>Submit</span>
    </button>
  );
}

function Spinner() {
  return (
    <svg
      className="animate-spin h-5 w-5 text-white"
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
    >
      <circle
        className="opacity-25"
        cx="12"
        cy="12"
        r="10"
        stroke="currentColor"
        strokeWidth="4"
      />
      <path
        className="opacity-75"
        fill="currentColor"
        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
      />
    </svg>
  );
}

Transition Loading

The useTransition hook marks state updates as non-blocking transitions. Use it for navigation or data refreshes to show loading feedback without blocking the UI.

"use client";

import { useTransition } from "react";
import { useRouter } from "next/navigation";

export default function RefreshButton() {
  const router = useRouter();
  const [isPending, startTransition] = useTransition();

  const handleRefresh = () => {
    startTransition(() => {
      router.refresh();
    });
  };

  return (
    <button
      onClick={handleRefresh}
      disabled={isPending}
      className="flex items-center gap-2 px-4 py-2 rounded-lg border"
    >
      <svg
        className={`w-4 h-4 ${isPending ? "animate-spin" : ""}`}
        fill="none"
        viewBox="0 0 24 24"
        stroke="currentColor"
      >
        <path
          strokeLinecap="round"
          strokeLinejoin="round"
          strokeWidth={2}
          d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"
        />
      </svg>
      {isPending ? "Refreshing..." : "Refresh"}
    </button>
  );
}

7. Toast Notifications

Toast notifications provide non-intrusive feedback for actions. They appear temporarily and auto-dismiss, making them ideal for success messages and non-critical errors.

This implementation uses React Context to provide toast functionality throughout the application. The ToastProvider manages the toast state and renders the toast container.

// components/Toast.tsx
"use client";

import { createContext, useContext, useState, useCallback } from "react";

interface Toast {
  id: string;
  message: string;
  type: "success" | "error" | "info";
}

interface ToastContextType {
  toasts: Toast[];
  addToast: (message: string, type: Toast["type"]) => void;
  removeToast: (id: string) => void;
}

const ToastContext = createContext<ToastContextType | null>(null);

export function ToastProvider({ children }: { children: React.ReactNode }) {
  const [toasts, setToasts] = useState<Toast[]>([]);

  const addToast = useCallback((message: string, type: Toast["type"]) => {
    const id = Date.now().toString();
    setToasts((prev) => [...prev, { id, message, type }]);

    // Auto remove after 5 seconds
    setTimeout(() => {
      setToasts((prev) => prev.filter((t) => t.id !== id));
    }, 5000);
  }, []);

  const removeToast = useCallback((id: string) => {
    setToasts((prev) => prev.filter((t) => t.id !== id));
  }, []);

  return (
    <ToastContext.Provider value={{ toasts, addToast, removeToast }}>
      {children}
      <ToastContainer toasts={toasts} removeToast={removeToast} />
    </ToastContext.Provider>
  );
}

export function useToast() {
  const context = useContext(ToastContext);
  if (!context) throw new Error("useToast must be used within ToastProvider");
  return context;
}

function ToastContainer({
  toasts,
  removeToast,
}: {
  toasts: Toast[];
  removeToast: (id: string) => void;
}) {
  return (
    <div className="fixed bottom-4 right-4 space-y-2 z-50">
      {toasts.map((toast) => (
        <div
          key={toast.id}
          className={`p-4 rounded-lg shadow-lg flex items-center gap-3 min-w-[300px] ${
            toast.type === "success"
              ? "bg-green-500 text-white"
              : toast.type === "error"
                ? "bg-red-500 text-white"
                : "bg-blue-500 text-white"
          }`}
        >
          <span className="flex-1">{toast.message}</span>
          <button onClick={() => removeToast(toast.id)}>✕</button>
        </div>
      ))}
    </div>
  );
}

Additional Resources

Next Lesson: Tailwind CSS v4 Setup & Basics