Overview

Component & UI Architecture

This section covers how to structure the UI layer at a system level. Individual components are the unit of composition, but the decisions that matter most are about boundaries — where server work ends and client interactivity begins, how errors are isolated, how behavior is decoupled from markup, how floating layers are coordinated, and how large teams own independent UI surfaces.

The section moves from the most foundational model (React Server Components) through progressively more advanced patterns, ending with large-scale orchestration concerns.

What's Covered

Server Components — React's model for server-only components that ship zero JavaScript to the client. Covers the server/client boundary, the cache() deduplication function, the server-only package, the taint API for preventing sensitive data leaks, parallel vs sequential fetch patterns, and the children composition pattern for mixing Server and Client Components.

Suspense Boundaries — How components suspend via thrown Promises, how streaming SSR uses boundaries as progressive rendering slots, how use() suspends Client Components from Server-passed Promises, and how startTransition prevents fallback re-triggering on state updates that cause re-suspension.

Error Boundaries — How getDerivedStateFromError (render-phase, pure) and componentDidCatch (commit-phase, side effects) work together. What errors boundaries catch and what they don't. Next.js error.tsx and global-error.tsx file-based boundaries. Handling async and event handler errors that boundaries miss. React 19 useActionState for form errors.

Compound Components — Sharing implicit state across cooperating subcomponents via React Context. The controlled/uncontrolled pattern. useId for hydration-safe ARIA IDs. ARIA roving tabindex for keyboard navigation. The polymorphic as prop. Passing Server Component children into Client Component compound roots.

Headless UI Pattern — Separating interaction logic, keyboard navigation, accessibility, and positioning entirely from markup. The prop getter pattern. Building a fully accessible combobox with complete keyboard interaction model. Floating UI for viewport-aware popup positioning. When to choose headless over compound components.

Portal & Layering Architecture — How createPortal escapes DOM containment while preserving the React tree. Stacking contexts and why z-index: 9999 fails. A named z-index CSS custom property scale. isolation: isolate for self-contained component layering. Focus trap implementation. The inert attribute for modal backgrounds. Backdrop-click detection.