---
overlay: React Specialization
parent_agent: Super Coder
description: "React component patterns and hooks"
---

## REACT-SPECIFIC GUIDELINES

You are working in a **React** codebase. Apply these principles with zero exceptions.

### Component Patterns — Functional Only
- **Always use functional components** — never class components for new code
- Keep components focused — if >150 lines, extract subcomponents
- Use composition over prop drilling: split into Container + Presentation components when logic is complex
- Export components as named exports: `export function UserCard() {}` — not default exports
- Co-locate related files: component, styles, tests, types in the same directory

### Hooks Rules — NON-NEGOTIABLE
- Hooks only at the **top level** — never inside conditions, loops, or nested functions
- Hooks only in **function components** or **custom hooks** — never in regular functions
- Custom hooks start with `use`: `useAuth()`, `useFetchUser()`
- Keep custom hooks focused on one responsibility — compose hooks, don't create mega-hooks
- Always provide proper dependency arrays for `useEffect`, `useMemo`, `useCallback`

### State Management
- Use `useState` for simple local state
- Use `useReducer` for complex state with multiple related updates
- Use **React Context** for truly global state (theme, auth, locale) — not for all shared state
- Avoid prop drilling >2 levels — extract to context or composition pattern
- State should live as close to where it's used as possible — lift only when necessary
- Never derive state from props in `useState` — compute it directly or use `useMemo`

### Performance — When to Optimize
- **Don't wrap everything in `memo`/`useMemo`/`useCallback`** — only optimize when there's a measured problem
- Use `React.memo()` when: component renders often with same props, rendering is expensive
- Use `useMemo()` when: computation is expensive AND dependencies change infrequently
- Use `useCallback()` when: passing callbacks to memoized child components
- Use `key` prop correctly — stable, unique IDs from data (never array index for dynamic lists)

### Error Boundaries
- Wrap major sections in error boundaries — prevent one component crash from taking down the page
- Use `react-error-boundary` or create a class-based boundary (the one exception to "no classes")
- Show meaningful fallback UI — not a blank page

### React 19+ Patterns (if applicable)
- Use `use()` hook for reading resources (promises, contexts)
- Use `useActionState()` for form actions with pending state
- Use `useOptimistic()` for optimistic UI updates
- Use `<form action={}>` with server actions where available

### Naming Conventions
- `PascalCase` for components: `UserProfile`, `LoginForm`
- `camelCase` for hooks: `useAuth`, `useFetchData`
- `camelCase` for event handlers with `handle` prefix: `handleClick`, `handleSubmit`
- `on` prefix for callback props: `onClick`, `onSubmit`, `onChange`
- Boolean props: `is*`, `has*`, `should*`: `isLoading`, `hasError`

### Testing Considerations
- Write components that are testable — props in, rendered output out
- Use data-testid attributes for test selectors (not CSS classes or element structure)
- Prefer composition and dependency injection over hard-coded dependencies