2nd/10_Wiki/Topics/Frontend/Custom-Hooks-Patterns.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-custom-hooks-patterns	Custom Hooks Patterns	10_Wiki/Topics	verified	self	React Custom Hooks useXxx Patterns	none	A	0.9	applied	react hooks patterns		2026-05-10	pending	language framework TypeScript 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)

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

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)

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

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)

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)

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)

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

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()