Skip to content
Skills Library
Programming · Building & coding

react-idioms

/react-idioms

React 19+ patterns: custom hooks, Suspense boundaries, state management, component composition, and web performance. Use when developing or refactoring React components and client applications. Pair with typescript-idioms.

Repository
awesome-agv ↗
Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

React 19+ patterns: custom hooks, Suspense boundaries, state management, component composition, and web performance. Use when developing or refactoring React components and client applications. Pair with typescript-idioms.

Original author description

React 19+ patterns: custom hooks, Suspense boundaries, state management, component composition, and web performance. Use when developing or refactoring React components and client applications. Pair with typescript-idioms.

How it works

  1. React Idioms and Patterns
  2. When to Load References
Original SKILL.md headings · 436 lines, 1,705 words
SKILL.md preview
---
name: react-idioms
description: >-
  React 19+ patterns: custom hooks, Suspense boundaries, state management, component composition, and web performance. Use when developing or refactoring React components and client applications. Pair with typescript-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.

| Situation | Reference to Load |
|---|---|
| Starting a React (Vite) project or reviewing file layout | `references/project-structure.md` + `@.agents/skills/frontend-design/references/frontend-layout.md` |
| TypeScript type system, async, Zod, error types | `@.agents/skills/typescript-idioms/SKILL.md` (always co-load) |
| Zod schemas / boundary validation | `@.agents/skills/typescript-idioms/references/zod-patterns.md` |
| Async / I/O / coercion pitfalls | `@.agents/skills/typescript-idioms/references/ts-patterns-and-anti-patterns.md` |
| Next.js App Router (RSC, Server Actions, caching) | `@.agents/skills/nextjs-idioms/SKILL.md` (use that skill instead for Next projects) |

---

### Component Patterns

1. **Functional components only** — no class components in new code.
2. **Composition over inheritance:**
   ```tsx
   // ✅ 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:
   ```tsx
   <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:**
   ```tsx
   // ✅ 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:**
   ```tsx
   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:
   ```tsx
   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:**
   ```tsx
   // ✅ 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:
   ```tsx
   // ✅ 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`):
   ```tsx
   // ✅ 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:
   ```tsx
   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:
   ```tsx
   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:
   ```tsx
   // ✅ 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:
   ```tsx
   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:
   ```tsx
   // ✅ 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:
   ```tsx
   // ✅ 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:
   ```tsx
   // ✅ 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)
   ```

---

### Error Handling

> For universal error handling principles, see `.agents/rules/error-handling-principles.md`.

1. **Error boundaries** for component tree errors — use `react-error-boundary` or a custom class component:
   ```tsx
   // ✅ Wrap feature subtrees, log in componentDidCatch
   <ErrorBoundary fallback={<ErrorMessage />}>
     <TaskList />
   </ErrorBoundary>
   ```

2. **TanStack Query** — use `retry`, `isError`, and `error` from query result (see State Management).

3. **Log errors** in `componentDidCatch` with `correlationId` and `componentStack` — never swallow silently.

---

### Performance

1. **`React.memo`** only when profiling shows unnecessary re-renders.
2. **Code splitting**: `React.lazy` + `Suspense` for route-level splitting:
   ```tsx
   import { lazy, Suspense } from 'react';

   const TaskPage    = lazy(() => import('./features/task/TaskPage'));
   const ProfilePage = lazy(() => import('./features/profile/ProfilePage'));

   function AppRoutes() {
     return (
       <Suspense fallback={<PageSkeleton />}>
         <Routes>
           <Route path="/tasks"   element={<TaskPage />} />
           <Route path="/profile" element={<ProfilePage />} />
         </Routes>
       </Suspense>
     );
   }
   ```
3. **Virtual scrolling** for long lists (TanStack Virtual).
4. **Image optimization** — use `loading="lazy"` and `srcSet` for responsive images.
5. **Avoid inline object/array literals in props** if causing re-render issues — hoist or `useMemo`.

---

### Anti-Patterns

- ❌ **`useEffect` for data fetching** — use TanStack Query, SWR, or loaders
- ❌ **Prop drilling through 3+ levels** — use Context or state manager
- ❌ **`key={index}` on dynamic lists** — use stable, unique identifiers
- ❌ **`useMemo`/`useCallback` on everything** — premature optimization
- ❌ **State for derived data** — compute during render:
  ```tsx
  // ❌ Unnecessary state
  const [filteredTasks, setFilteredTasks] = useState<Task[]>([]);
  useEffect(() => {
    setFilteredTasks(tasks.filter(t => t.status === filter));
  }, [tasks, filter]);

  // ✅ Computed during render — no extra state
  const filteredTasks = tasks.filter(t => t.status === filter);
  ```
- ❌ **Direct DOM manipulation** — use refs and React's render cycle
- ❌ **`useFormState`** — replaced by `useActionState` in React 19
- ❌ **Global state for server data** — use TanStack Query/SWR instead

---

### Testing

> For universal testing principles, see `.agents/rules/testing-strategy.md`. Below: React-specific patterns only.

React Testing Library + Vitest/Jest. Test behavior, not implementation.

1. **Component rendering and interaction:**
   ```tsx
   import { render, screen, fireEvent } from '@testing-library/react';

   test('displays task title', () => {
     render(<TaskCard task={mockTask} />);
     expect(screen.getByText('Deploy fix')).toBeInTheDocument();
   });

   test('calls onComplete when button clicked', async () => {
     const onComplete = vi.fn();
     render(<TaskCard task={mockTask} onComplete={onComplete} />);

     await fireEvent.click(screen.getByRole('button', { name: /complete/i }));

     expect(onComplete).toHaveBeenCalledWith(mockTask.id);
   });
   ```

2. **Provider wrapper for tests** — wrap components that depend on providers:
   ```tsx
   function createTestWrapper() {
     const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
     return ({ children }: { children: React.ReactNode }) => (
       <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
     );
   }

   render(<TaskList />, { wrapper: createTestWrapper() });
   ```

3. **Testing custom hooks** with `renderHook`:
   ```tsx
   import { renderHook, waitFor } from '@testing-library/react';

   test('useTask returns task data', async () => {
     const { result } = renderHook(() => useTask('1'), {
       wrapper: createTestWrapper(),
     });

     await waitFor(() => expect(result.current.task).toBeDefined());
     expect(result.current.task?.title).toBe('Deploy fix');
   });
   ```

4. **MSW for API mocking** — intercept at the network level:
   ```tsx
   import { http, HttpResponse } from 'msw';
   import { setupServer } from 'msw/node';

   const server = setupServer(
     http.get('/api/tasks', () =>
       HttpResponse.json([{ id: '1', title: 'Deploy fix', status: 'todo' }])
     ),
   );

   beforeAll(() => server.listen());
   afterEach(() => server.resetHandlers());
   afterAll(() => server.close());
   ```

---

### Formatting and Static Analysis

| Tool | Purpose | Command |
|---|---|---|
| Prettier | Formatting | `npx prettier --write .` |
| ESLint + eslint-plugin-react-hooks | Linting | `npx eslint .` |
| TypeScript | Type checking | `npx tsc --noEmit` |

---

### Related
- Code Idioms and Conventions @.agents/rules/code-idioms-and-conventions.md
- TypeScript Idioms @.agents/skills/typescript-idioms/SKILL.md
- React Project Structure @.agents/skills/react-idioms/references/project-structure.md
- Frontend Layout (framework-neutral, shared with Vue) @.agents/skills/frontend-design/references/frontend-layout.md
- Frontend Design @.agents/skills/frontend-design/SKILL.md
- Next.js Idioms (for Next.js App Router projects) @.agents/skills/nextjs-idioms/SKILL.md
- Security Principles @.agents/rules/security-principles.md
- Accessibility Principles @.agents/rules/accessibility-principles.md
- Testing Strategy @.agents/rules/testing-strategy.md
- Error Handling Principles @.agents/rules/error-handling-principles.md
- Logging and Observability @.agents/rules/logging-and-observability-mandate.md
- Architectural Patterns @.agents/rules/architectural-pattern.md
Files in this package (2)
  • SKILL.md 15 KB
  • references/project-structure.md 3 KB

Versions

The database has no other skills named react-idioms.

Database snapshot: 13.11.2026 · package version 7d629b79044e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 1 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100react-patterns
    React 18/19 patterns including hooks discipline, server/client component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.
  • 100react-patterns
    React 18/19 patterns including hooks discipline, server/client component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.
  • 100react-patterns
    React 18/19 patterns including hooks discipline, server/client component boundaries, Suspense + error boundaries, form actions, data fetching, state management decision trees, and accessibility-first composition. Use when writing or reviewing React components.
  • 100react-expert
    Use when building React 19.2+ applications requiring component architecture, hooks patterns, or state management. Invoke for Server Components, performance optimization, Suspense boundaries, React 19 features, <Activity>, useEffectEvent, cacheSignal.
  • 100react
    Core React 19 patterns including hooks, Suspense, lazy loading, component structure, TypeScript best practices, and performance optimization. Use when working with React components, hooks, lazy loading, Suspense boundaries, or React-specific TypeScript patterns.
  • 100developing-with-react
    React 18+ development with hooks, state management, component patterns, and Next.js integration. Use when building React applications or working with JSX/TSX components.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.