React Component Patterns

Server vs Client (Next.js App Router)

Composition pattern — pass Server Components as children into Client wrappers:

// page.tsx (server)
<ClientShell hero={<HeroSection />} />

// client-shell.tsx
"use client";
export function ClientShell({ hero }: { hero: React.ReactNode }) {
  return <>{hero}<InteractivePanel /></>;
}

Folder conventions

components/
  ui/           → primitives (Button, Dialog) — mostly client
  layout/       → Header, Footer, SkipToMain
  {feature}/    → domain screens composed from ui/

One component per file; named export matching filename.

forwardRef for primitives

Wrap Radix/DOM elements when parents need refs:

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, ...props }, ref) => (
    <button ref={ref} className={cn("...", className)} {...props} />
  )
);
Button.displayName = "Button";

Invalid nesting — common fixes

Guard delegated clicks:

function isInteractiveChild(target: EventTarget | null) {
  return target instanceof Element && Boolean(target.closest("button, a, input, select, textarea"));
}

Lists and keys

• Key = stable id, never array index for reorderable lists
• Extract row component when rows have state or handlers

Props design

• Prefer narrow props over passing entire store
• children for layout slots; render props only when caller needs data back
• Colocate types: interface FooProps above component

Loading and suspense

const HeavyStep = lazy(() => import("./heavy-step"));

<Suspense fallback={<Skeleton />}>
  <HeavyStep />
</Suspense>

Anti-patterns

• "use client" on entire pages when only a CTA needs interactivity
• Prop drilling 5+ levels — use context or client store instead
• Deriving state in render that should be useMemo
• Icon-only buttons without aria-label