jaykim88/async-ux-states

Async UX States

Purpose

Every asynchronous view in the app handles the three states (loading, error, empty) completely. No white screens, no undefined exposed to users, no untrapped errors.

Universal — the 3-state pattern (loading / error / empty), custom 404/500 pages, Error Boundary placement, and Suspense-boundary granularity exist in every modern meta-framework. Only the file-naming conventions and component APIs differ.

Procedure

1. Audit loading states

   • Find every component that fetches data (fetch, useQuery, useSWR, Server Components)
   • Verify each has a loading representation; skeleton should match the actual content size (avoid CLS)
   • Delay the loader ~200–300ms so fast responses don't flash a spinner; skeleton for layout-known content, spinner for short/unknown
   • On refetch (pagination, filter change), keep the previous data with a subtle loading indicator instead of blanking to a skeleton — big perceived-perf win (coordinate with api-caching-optimization)
   • Set a fetch timeout — an unresolved fetch is an infinite spinner, the white screen this skill exists to kill; after N seconds, fall through to the error state
   • Mark the region aria-busy while loading; give skeletons an SR-only "Loading…" label

2. Audit error states — match the action to the error type

   • Every fetch path must have an error UI; message is recoverable + actionable + non-technical
   • The right action depends on the error kind — a generic "Retry" is wrong for most:
     • Network / offline / timeout → "Check your connection" + retry (transient)
     • 401 / 403 auth → prompt sign-in or "you don't have access" — not retry
     • 404 not found → navigate elsewhere; retry won't help
     • 5xx server → "something went wrong" + retry + report
   • Retry with bounded exponential backoff, not instant/infinite loops that hammer a failing server (frameworks pass a reset/retry fn into the error boundary — see Implementation)
   • Announce the error in a role="alert" / aria-live region and move focus to it (keyboard / SR users)
   • Log to observability (Sentry, etc.) but never expose a stack trace to the user

3. Audit empty states

   • Empty ≠ error — a successful fetch returning 0 items
   • Should explain what would appear here and how to get there (CTA)
   • Example: empty inbox → "No messages yet — invite teammates to start a conversation"

4. Place error/loading boundary files at the correct route segment

   • Loading boundary: at the segment that owns the slow data fetch
   • Error boundary: cannot catch errors from its same-level layout — place at the parent segment
   • Root-level layout errors require a dedicated global error handler
   • Not-found: at root + any segment where 404 is a valid outcome
   • See Implementation for framework-specific file naming conventions

5. Customize 404 and 500 pages

   • 404: helpful navigation back to known good routes
   • 500: "something went wrong" + retry + link home
   • Both branded, not default browser pages

6. Suspense boundary granularity

   • One huge boundary at page root = entire page blocks on slowest fetch
   • Multiple small boundaries = fast sections render independently
   • Default: one per major content section

7. Error Boundary fallback UI

   • Inside dynamic sections (e.g., third-party widget), wrap with a component-level error boundary
   • Pair granular error boundaries with granular Suspense (step 6): one failed/slow island degrades in place instead of blanking the whole page
   • Fallback offers "reload this section" or "go home"
   • Falls back to safe known UI, never a stack trace

8. Verify (validation loop)

   • For each async view, force all three states (throttle/offline the network, return [], throw) and confirm the right UI — never a blank screen, undefined, or infinite spinner
   • Confirm errors are announced and focusable, and that a slow/failed island doesn't blank the page
   • In observability: the "white screen" / unhandled-error category trends to 0; track empty-state CTA click-through to validate copy
   • Loop until every view passes all three states

Severity tiers

| Tier | Examples | Action SLA | |---|---|---| | Critical | Blank/white screen or raw undefined shown; an unhandled error crashes the whole route; infinite spinner (no timeout) | Block release; fix immediately | | Major | Async view missing an error or empty state; generic "Retry" shown for a 401/403/404; stack trace exposed to users; error not announced to screen readers | Fix this sprint | | Minor | Spinner flash on fast responses; skeleton size mismatch (CLS); empty state without a CTA | Schedule within 2 sprints |

Completion Criteria

• [ ] Every async view has loading / error / empty states
• [ ] Fetches have a timeout — no infinite spinners
• [ ] Error action matches error type (no "Retry" on 401/403/404); retry uses backoff
• [ ] Errors announced (role="alert"/aria-live) and focusable
• [ ] Custom 404 and 500 pages implemented
• [ ] error.tsx placed at correct segment (not same as throwing layout)
• [ ] Suspense boundaries are granular (no full-page blocking)
• [ ] Sentry "blank screen" errors = 0 in last week

Output

• 3-state components: each async view has loading / error / empty UI
• Framework special files: loading.tsx, error.tsx, not-found.tsx, global-error.tsx placed at correct segments
• Error Boundary wrappers: around third-party widgets and dynamic sections
• Audit report (paste into PR): list of routes audited / 3-state coverage / Suspense boundary placement decisions
• Commit format: feat(error-ux): add 3-state to <view> or fix(error-ux): correct error.tsx placement at <segment>

Implementation

React + Next.js (default)

• App Router special files: loading.tsx / error.tsx / not-found.tsx / global-error.tsx
• error.tsx cannot catch errors in its same-segment layout.tsx — place at parent segment; for root layout, only global-error.tsx catches
• Retry: reset (or unstable_retry in Next.js 16.2+) prop passed to error.tsx
• Component-level: React ErrorBoundary, or unstable_catchError from next/error (Next.js 16.2+, API may change) — unstable_catchError(fallback) returns a wrapper; fallback receives (props, { error, unstable_retry, reset })
• Timeout + backoff + keep-previous: AbortSignal.timeout(ms) on fetch; TanStack Query retry + retryDelay (exponential), placeholderData: keepPreviousData to avoid blanking on refetch
• Loader delay: a delayed Suspense fallback, or CSS animation-delay so the spinner only appears if the fetch is actually slow
• Suspense: <Suspense fallback={...}> boundaries

Other stacks

• Vue / Nuxt: error.vue for global errors; <NuxtErrorBoundary> for component-level; <Suspense> for async components; useFetch returns error ref for inline error state
• SvelteKit: +error.svelte at any route level catches errors from load() and child components; +loading.svelte for streaming; goto('/') for retry after fix
• Angular: global ErrorHandler injectable for uncaught errors; route-level resolve() errors handled by Router events; *ngIf patterns for empty states
• Universal: 3-state pattern (loading / error / empty) is framework-agnostic; the test "does refresh show the correct skeleton?" works for any stack; 404/500 pages need framework's route fallback API

Related skills

• render-strategy-decision — Suspense placement is part of route strategy
• observability-setup — error UI must coordinate with Sentry error capture
• form-ux — form-specific errors handled there

Reference

• Key insight encoded: error.tsx does NOT catch errors thrown in the same-segment layout.js — place error.tsx at the parent segment. Co-locate loading.tsx at the smallest subtree that does data fetching so Suspense fallbacks stay granular instead of blanking entire routes. Match the recovery action to the error type — a generic "Retry" is wrong for 401/403/404. An unresolved fetch is an infinite spinner (a white screen by another name) — always set a timeout.