React Idioms

React Idioms and Patterns

Core Philosophy

React 19+ rewards composition, hooks, and server-aware patterns. Idiomatic React = functional, performant, accessible. Prefer co-located features, custom hooks for logic reuse, and server state libraries over hand-rolled fetch logic.

Scope: This file covers React-specific coding idioms for components, hooks, state, routing, and forms. For TypeScript type system patterns, see @.agents/skills/typescript-idioms/SKILL.md. For file and folder layout, see references/project-structure.md (and the shared @.agents/skills/frontend-design/references/frontend-layout.md). For general frontend design, see @.agents/skills/frontend-design/SKILL.md.

Loading guard: If the project uses Next.js (App Router — app/ dir or next.config.*), load @.agents/skills/nextjs-idioms/SKILL.md instead of this skill for App-Router-specific patterns. This skill still applies to client components and pure-React (Vite) SPAs.

When to Load References

Load these before writing code in the matching context — not after.

---

Component Patterns

1. Functional components only — no class components in new code.

2. Composition over inheritance:

   // ✅ Compound components
   <Card>
     <Card.Header>{title}</Card.Header>
     <Card.Body>{children}</Card.Body>
   </Card>

3. Error boundaries for graceful failure — wrap feature subtrees to catch render errors.

4. Render props for flexible, headless composition:

   <DataLoader url="/api/tasks">
     {({ data, isLoading, error }) => {
       if (isLoading) return <Skeleton />;
       if (error) return <ErrorMessage error={error} />;
       return <TaskList tasks={data} />;
     }}
   </DataLoader>

5. Props typing — always explicit:

   // ✅ Typed props with defaults
   interface TaskCardProps {
     task: Task;
     onComplete?: (taskId: string) => void;
     variant?: 'compact' | 'expanded';
   }
   
   export function TaskCard({ task, onComplete, variant = 'compact' }: TaskCardProps) {
     // ...
   }

6. One concern per component — if a component exceeds ~100 JSX lines, extract a sub-component.

---

Hooks

1. Custom hooks for reusable logic:

   function useTask(id: string) {
     const { data, error, isLoading } = useQuery({
       queryKey: ['task', id],
       queryFn: () => taskApi.getTask(id),
     });
     return { task: data, error, isLoading };
   }

2. useMemo/useCallback only for measured performance issues — not by default.

3. useEffect cleanup — always return cleanup function for subscriptions:

   useEffect(() => {
     const controller = new AbortController();
   
     fetchTasks(controller.signal).then(setTasks);
   
     return () => controller.abort(); // ✅ Cleanup on unmount
   }, []);

4. useRef for values that don't trigger re-renders:

   // ✅ Timer ref — doesn't cause re-render
   const timerRef = useRef<ReturnType<typeof setInterval>>();
   
   useEffect(() => {
     timerRef.current = setInterval(pollStatus, 5000);
     return () => clearInterval(timerRef.current);
   }, []);

---

React 19 Patterns

1. use() hook — read resources, promises, and context directly in render:

   // ✅ Read a promise during render (replaces useEffect + useState)
   function TaskDetail({ taskPromise }: { taskPromise: Promise<Task> }) {
     const task = use(taskPromise);
     return <h1>{task.title}</h1>;
   }
   
   // ✅ Read context without useContext
   function TaskActions() {
     const theme = use(ThemeContext);
     return <button className={theme.primaryBtn}>Save</button>;
   }

2. useActionState for form actions (replaces useFormState):

   // ✅ Server-aware form with pending state
   async function createTask(_prev: State, formData: FormData) {
     const result = await api.createTask(Object.fromEntries(formData));
     return result.error ? { error: result.error } : { success: true };
   }
   
   function TaskForm() {
     const [state, formAction, isPending] = useActionState(createTask, { error: null });
     return (
       <form action={formAction}>
         <input name="title" required />
         {state.error && <p className="error">{state.error}</p>}
         <button disabled={isPending}>{isPending ? 'Saving…' : 'Create'}</button>
       </form>
     );
   }

3. useOptimistic for instant UI feedback:

   const [optimisticTasks, addOptimistic] = useOptimistic(
     tasks,
     (state, newTask: Task) => [...state, newTask],
   );
   // Call addOptimistic(tempTask) before await api.createTask(tempTask)

4. <form action={fn}> for progressive enhancement — works before JS loads (see useActionState example above).

---

Form Handling

1. React Hook Form + Zod for validated forms:

   import { useForm } from 'react-hook-form';
   import { zodResolver } from '@hookform/resolvers/zod';
   import { z } from 'zod';
   
   const taskSchema = z.object({
     title: z.string().min(1, 'Title is required').max(200),
     priority: z.enum(['low', 'medium', 'high']),
   });
   type TaskFormData = z.infer<typeof taskSchema>;
   
   function TaskForm({ onSubmit }: { onSubmit: (data: TaskFormData) => Promise<void> }) {
     const { register, handleSubmit, formState: { errors } } = useForm<TaskFormData>({
       resolver: zodResolver(taskSchema),
     });
     return (
       <form onSubmit={handleSubmit(onSubmit)}>
         <input {...register('title')} />
         {errors.title && <p>{errors.title.message}</p>}
         <button type="submit">Create</button>
       </form>
     );
   }

2. Controlled vs uncontrolled decision:

   • Use uncontrolled (register) for simple forms — better performance, less boilerplate
   • Use controlled (Controller) when the UI must react to every keystroke (live previews, dependent fields)

---

Routing

1. React Router 7 data patterns — loaders and actions:

   // ✅ Route-level data loading
   export async function loader({ params }: LoaderFunctionArgs) {
     return taskApi.getTask(params.id!);
   }
   
   export function TaskPage() {
     const task = useLoaderData<typeof loader>();
     return <TaskDetail task={task} />;
   }

2. TanStack Router for type-safe routes:

   const taskRoute = createRoute({
     getParentRoute: () => rootRoute,
     path: '/tasks/$taskId',
     loader: ({ params }) => taskApi.getTask(params.taskId),
     component: TaskPage,
   });

3. Route-level code splitting — always lazy-load route components with React.lazy + Suspense (see Performance section).

---

State Management

Decision tree: useState → useContext → Zustand → TanStack Query (for server state)

1. Local state first (useState), lift only when shared by siblings.
2. Server state: TanStack Query — never in global state:

   // ✅ Server state managed by TanStack Query
   function useTasks() {
     return useQuery({
       queryKey: ['tasks'],
       queryFn: () => taskApi.getTasks(),
       staleTime: 5 * 60 * 1000,
     });
   }

3. Client state: Context for small/infrequent updates, Zustand/Jotai for complex/frequent:

   // ✅ features/task/store/task.store.ts — Zustand for UI-only state
   import { create } from 'zustand';
   
   interface TaskUIState {
     selectedId: string | null;
     filter: 'all' | 'active' | 'done';
     selectTask: (id: string | null) => void;
     setFilter: (f: TaskUIState['filter']) => void;
   }
   
   export const useTaskUIStore = create<TaskUIState>((set) => ({
     selectedId: null,
     filter: 'all',
     selectTask: (id) => set({ selectedId: id }),
     setFilter: (filter) => set({ filter }),
   }));
   
   // Usage — client UI state only; server data stays in TanStack Query
   function TaskToolbar() {
     const { filter, setFilter } = useTaskUIStore();
     return <FilterBar value={filter} onChange={setFilter} />;
   }

4. I/O isolation — abstract API behind an interface for testability:

   // ✅ features/task/api/task.api.ts — interface
   export interface TaskAPI {
     getTasks(): Promise<Task[]>;
     createTask(data: CreateTaskDTO): Promise<Task>;
   }
   
   // ✅ features/task/api/task.api.backend.ts — production (implements TaskAPI with fetch)
   // ✅ features/task/api/task.api.mock.ts — test (implements TaskAPI with in-memory data)

---