Loading and Error States

A screen that loads data has four outcomes, not one. It can be waiting, it can have failed, it can have succeeded with nothing to show, and it can have succeeded with data.

All four are part of the design. The reason so many applications handle them badly is that the fourth is the only one anyone thinks about while building, and the others get bolted on after someone reports a blank page.

One distinction is worth stating plainly, because getting it wrong is common: an empty list is not an error. A filter that matches no employees is the system working correctly. Showing a red failure message for it tells the user something is broken when nothing is.

// Three separate flags allow states that make no sense:
// isLoading true and error set, or data present while still loading.
interface LooseState {
  isLoading: boolean;
  error: string | null;
  employees: Employee[];
}

// One value with four shapes. Anything not listed here cannot occur.
type DirectoryState =
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "empty" }
  | { status: "ready"; employees: Employee[] };

• The loose version has eight combinations of its two flags and its array, and only four of them mean anything. The other four are bugs waiting for a code path that produces them.
• The union gives each state its own shape, and each shape carries exactly the data that state needs. There is no message when you are loading and no employees when you have failed, because those fields do not exist there.
• TypeScript narrows by the status field, so inside a check for status === "ready" the employees array is known to exist. Reading it in the error branch does not compile — the compiler enforces the design.
• Whether "empty" deserves its own status or is derived from a ready state with a zero-length array is a fair question. Keeping it separate makes the four branches explicit in the type and stops anyone forgetting it; deriving it is less code. Either way, handle it.

"use client";

import { useEffect, useState } from "react";

export function EmployeeDirectory({ department }: { department: string }) {
  const [state, setState] = useState<DirectoryState>({ status: "loading" });
  const [attempt, setAttempt] = useState(0);

  useEffect(() => {
    const controller = new AbortController();
    let ignore = false;

    setState({ status: "loading" });

    fetch("/api/employees?department=" + encodeURIComponent(department), {
      signal: controller.signal,
    })
      .then((response) => {
        if (!response.ok) throw new Error(String(response.status));
        return response.json() as Promise<Employee[]>;
      })
      .then((employees) => {
        if (ignore) return;
        setState(
          employees.length === 0
            ? { status: "empty" }
            : { status: "ready", employees }
        );
      })
      .catch((caught: Error) => {
        if (ignore || caught.name === "AbortError") return;
        setState({ status: "error", message: "We could not load the directory." });
      });

    return () => {
      ignore = true;
      controller.abort();
    };
  }, [department, attempt]);

  return (
    <div aria-live="polite" aria-busy={state.status === "loading"}>
      {state.status === "loading" && <EmployeeTableSkeleton rows={5} />}

      {state.status === "error" && (
        <div role="alert">
          <p>{state.message}</p>
          <button type="button" onClick={() => setAttempt((count) => count + 1)}>
            Try again
          </button>
        </div>
      )}

      {state.status === "empty" && (
        <p>No employees in {department} yet. Add one to get started.</p>
      )}

      {state.status === "ready" && <EmployeeTable employees={state.employees} />}
    </div>
  );
}

• Every branch is written out, so there is no path through this component that renders nothing. A blank screen is the usual symptom of a missing branch.
• The retry works by incrementing a counter that is in the effect's dependencies. That makes retrying a re-run of the same synchronisation rather than a separate code path, so it cannot drift from the original request.
• aria-live="polite" on the container means a screen reader announces the content when it changes, which is how someone who cannot see the skeleton learns that results have arrived. aria-busy says the region is still working.
• role="alert" on the error makes that announcement immediate rather than polite, which is appropriate for a failure the user has to act on.
• The error message is written for the person reading it. It does not include the status code — that belongs in a log, where it helps, not on screen, where it does not.
• The empty state suggests the next action. "No results" is a dead end; "add one to get started" is a way forward.