react
Build accessible React interfaces with function components, hooks, and deliberate state ownership; troubleshoot effects, list keys, and interactive behavior.
SKILL.mdskills/react/SKILL.md
GitHubReact UI Engineering AI Skill Guide (Claude)
Overview & Engine Architecture
React renders a component tree of functions returning UI. State updates schedule re-renders; hooks attach state, context, refs, and effects. React 18+ Concurrent features and React 19 refinements (Actions, use, document metadata hooks in frameworks) change how async and transitions behave—effects still run after paint; Strict Mode double-invokes effects in development to surface missing cleanup.
Claude operates as a Principal UI Engineer: pure render logic, minimal effects, accessible controls, and stable list identity.
Render (derive from props/state)
→ commit DOM
→ useLayoutEffect (sync after DOM)
→ useEffect (async after paint)
When to use / when not to
Use when
- Building interactive UI, forms, and client islands (
"use client"in Next.js). - Refactoring prop drilling into composition or colocated context.
- Fixing infinite loops, stale closures, and a11y failures.
Do not use when
- All data and interactivity can stay on the server (Next.js Server Components)—avoid unnecessary client bundles.
- Global state library migration is a team process—don't introduce Redux/Zustand without convention.
Operational Capabilities & Agent Directives
- Derive during render—don't mirror props into state (
fullName = first + last). - Effects for external sync only (subscriptions, imperative DOM, analytics)—not for transforming props to state.
- Dependency arrays must be honest; exhaustive-deps lint is your friend.
- Keys: Stable unique IDs for reorderable lists—never index-as-key when order changes.
- Accessibility: Real
<button>,<label htmlFor>, keyboard focus; don't click-only<div>. - React 19 / Actions: Prefer
useTransition+ server actions (in Next) for mutations instead of manual loading flags when appropriate. - Don't fetch in useEffect for initial page data when a server layer exists (
@nextjs).
Patterns
Controlled input:
function Search({ value, onChange }: { value: string; onChange: (v: string) => void }) {
return (
<label>
Search
<input value={value} onChange={(e) => onChange(e.target.value)} />
</label>
);
}
Functional updates (avoid stale state):
setCount((c) => c + 1);
Technical Troubleshooting Matrix
| Bug | Cause | Fix |
|---|---|---|
| Infinite re-render | Effect sets state that retriggers effect | Remove cycle; derive |
| Stale handler | Missing deps | Fix deps or functional updates |
| Lost focus | Unstable keys remount subtree | Stable keys on list items |
| Double fetch in dev | Strict Mode | Ensure idempotent effects + cleanup |
| Hydration error | Server HTML ≠ client first render | Gate client-only UI with useEffect or suppress only when safe |
| "Cannot update during render" | setState in render body | Move to event handler/effect |
Best practices
- Colocate state at lowest common ancestor.
- Error boundaries for recoverable regions.
- Test with Testing Library (
getByRole,getByLabelText). - Side effects and network mutations: dedicated hooks or server layer.
- Memoize (
useMemo,useCallback) only when profiling shows cost.
Limitations
- React doesn't include routing, data fetching, or CSS strategy—framework choices matter.
- Concurrent rendering can interrupt renders—avoid non-idempotent render side effects.
- Server Components (Next.js) cannot use most hooks—split client boundaries.
Related skills
@nextjs— RSC vs client boundaries@typescript— prop and hook typing@vitest— component unit tests@playwright— E2E behavior
Agent Operational Directive
MANDATORY: Prefer derived state over effect-synced state. Fix effect dependency bugs instead of disabling lint. Use semantic HTML and role-based queries in tests. Do not mark entire apps
"use client"to avoid thinking about server boundaries.
Sources
- React docs — hooks, Strict Mode, useEffect
- React 19 release notes — Actions, concurrent updates