---
id: wiki-2026-0508-custom-hooks-patterns
title: Custom Hooks Patterns
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [React Custom Hooks, useXxx Patterns]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [react, hooks, patterns]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: React 19
---

# Custom Hooks Patterns

## 매 한 줄
> **"매 custom hook = stateful logic 의 재사용 unit, JSX 의 X."**. React 19 (2024) `use()` + Server Components 시대에는 custom hook이 매 client-side state machine + side effect orchestration 의 primary abstraction. 매 naming은 `useXxx` — 매 ESLint react-hooks rule 의 enforce.

## 매 핵심

### 매 규칙 (Rules of Hooks)
- Top-level 만 호출 — 매 conditional / loop X.
- React function / 매 다른 hook 안에서 만 — 매 일반 function X.
- Naming `useXxx` — 매 lint 가 의존.

### 매 composition
- Hook = 매 다른 hook 의 조합 — `useMutation` ← `useState` + `useCallback` + `useRef`.
- 매 stateful logic 의 분리 + 매 testable 단위.

### 매 응용
1. Data fetching — `useQuery`, `useSWR`.
2. DOM observation — `useIntersectionObserver`, `useResizeObserver`.
3. State machines — `useToggle`, `useReducer` wrapper.
4. Browser API — `useLocalStorage`, `useMediaQuery`, `useGeolocation`.

## 💻 패턴

### 1. useToggle (state primitive)
```typescript
import { useState, useCallback } from 'react';

export function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn((v) => !v), []);
  const setOnTrue = useCallback(() => setOn(true), []);
  const setOnFalse = useCallback(() => setOn(false), []);
  return { on, toggle, setOnTrue, setOnFalse };
}
```

### 2. useDebouncedValue
```typescript
import { useEffect, useState } from 'react';

export function useDebouncedValue<T>(value: T, delayMs = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delayMs);
    return () => clearTimeout(id);
  }, [value, delayMs]);
  return debounced;
}
```

### 3. useEventListener (typed)
```typescript
import { useEffect, useRef } from 'react';

export function useEventListener<K extends keyof WindowEventMap>(
  type: K,
  handler: (e: WindowEventMap[K]) => void,
  target: Window | HTMLElement = window,
) {
  const handlerRef = useRef(handler);
  useEffect(() => { handlerRef.current = handler; });
  useEffect(() => {
    const listener = (e: Event) => handlerRef.current(e as WindowEventMap[K]);
    target.addEventListener(type, listener);
    return () => target.removeEventListener(type, listener);
  }, [type, target]);
}
```

### 4. useIntersectionObserver
```typescript
import { useEffect, useRef, useState } from 'react';

export function useIntersectionObserver<T extends Element>(
  options: IntersectionObserverInit = {},
) {
  const ref = useRef<T>(null);
  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
  useEffect(() => {
    if (!ref.current) return;
    const obs = new IntersectionObserver(([e]) => setEntry(e), options);
    obs.observe(ref.current);
    return () => obs.disconnect();
  }, [options.root, options.rootMargin, options.threshold]);
  return { ref, entry, isVisible: entry?.isIntersecting ?? false };
}
```

### 5. useLocalStorage (with sync)
```typescript
import { useEffect, useState } from 'react';

export function useLocalStorage<T>(key: string, initial: T) {
  const [value, setValue] = useState<T>(() => {
    const raw = localStorage.getItem(key);
    return raw ? (JSON.parse(raw) as T) : initial;
  });
  useEffect(() => {
    localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);
  useEffect(() => {
    const onStorage = (e: StorageEvent) => {
      if (e.key === key && e.newValue) setValue(JSON.parse(e.newValue));
    };
    window.addEventListener('storage', onStorage);
    return () => window.removeEventListener('storage', onStorage);
  }, [key]);
  return [value, setValue] as const;
}
```

### 6. useFetch (with AbortController)
```typescript
import { useEffect, useState } from 'react';

export function useFetch<T>(url: string) {
  const [state, setState] = useState<{ data?: T; error?: Error; loading: boolean }>({ loading: true });
  useEffect(() => {
    const ac = new AbortController();
    setState({ loading: true });
    fetch(url, { signal: ac.signal })
      .then((r) => r.json())
      .then((data: T) => setState({ data, loading: false }))
      .catch((error: Error) => {
        if (error.name !== 'AbortError') setState({ error, loading: false });
      });
    return () => ac.abort();
  }, [url]);
  return state;
}
```

### 7. useReducer composite (state machine)
```typescript
import { useReducer } from 'react';

type State = { status: 'idle' | 'loading' | 'success' | 'error'; data?: unknown; error?: Error };
type Action = { type: 'fetch' } | { type: 'success'; data: unknown } | { type: 'error'; error: Error };

const reducer = (s: State, a: Action): State => {
  switch (a.type) {
    case 'fetch': return { status: 'loading' };
    case 'success': return { status: 'success', data: a.data };
    case 'error': return { status: 'error', error: a.error };
  }
};

export const useAsync = () => useReducer(reducer, { status: 'idle' });
```

### 8. React 19 `use()` for promises
```typescript
import { use, Suspense } from 'react';

function Profile({ promise }: { promise: Promise<User> }) {
  const user = use(promise); // suspends until resolved
  return <h1>{user.name}</h1>;
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Local boolean | `useToggle`. |
| Server data | `useQuery` (TanStack Query) — 매 wheel 재발명 X. |
| 매 cross-tab sync | `useLocalStorage` + `storage` event. |
| Async resource | React 19 `use()` + Suspense. |
| 복잡 state | `useReducer` 매 state machine. |
| 매 DOM measurement | `useResizeObserver`, `useIntersectionObserver`. |

**기본값**: 매 TanStack Query / Zustand 의 use — custom hook은 매 truly specific logic 만.

## 🔗 Graph
- 부모: [[React]]
- 변형: [[Vue Composables]]
- 응용: [[Component Library]] · [[Design System]]
- Adjacent: [[useEffect]] · [[State Management]]

## 🤖 LLM 활용
**언제**: 매 hook scaffolding, TS generic 작성, 매 cleanup logic.
**언제 X**: 매 stale-closure / dep array 미세 bug — 매 manual review 필요.

## ❌ 안티패턴
- **Conditional hook call**: 매 `if (x) useFoo()` — 매 lint error.
- **Stale closure in setInterval**: 매 ref pattern 또는 functional setState 사용.
- **Effect for derived state**: 매 `useMemo` 또는 render 중 계산 — `useEffect` X.
- **No cleanup**: 매 listener / subscription 미해제 — leak.

## 🧪 검증 / 중복
- Verified (react.dev, React 19 release notes).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — React 19 hook patterns + use() |