2nd/10_Wiki/Topics/Coding/React_Refs_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
react-refs-patterns	React Refs 사용 패턴	Coding	draft	B	conceptual	2026-05-09	2026-05-09	react refs dom vibe-coding	language applicable_to TypeScript / React 18+ Web React Native		useRef forwardRef callback ref

React Refs 사용 패턴

ref 는 두 가지: (1) DOM 참조 — 측정/포커스/스크롤, (2) 렌더에 영향 안 주는 mutable 값 보관. ref.current 변경은 재렌더 trigger 안 함.

📖 핵심 개념

• DOM 또는 자식 imperative API 노출 (focus, play, scrollTo 등).
• 렌더 사이 보존하는 값 — previous value, timer id, mutable 카운터.
• ref 변경은 재렌더 안 함 (state 가 아님).

💻 코드 패턴

DOM 측정

function AutoFocus() {
  const inputRef = useRef<HTMLInputElement>(null);
  useEffect(() => { inputRef.current?.focus(); }, []);
  return <input ref={inputRef} />;
}

Previous value

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T>();
  useEffect(() => { ref.current = value; }, [value]);
  return ref.current;
}

Imperative handle 노출

type VideoHandle = { play: () => void; pause: () => void };

const Video = forwardRef<VideoHandle, { src: string }>((props, ref) => {
  const videoRef = useRef<HTMLVideoElement>(null);
  useImperativeHandle(ref, () => ({
    play: () => videoRef.current?.play(),
    pause: () => videoRef.current?.pause(),
  }), []);
  return <video ref={videoRef} src={props.src} />;
});

Callback ref (DOM 노드 변경 감지)

const measureRef = useCallback((node: HTMLDivElement | null) => {
  if (node) console.log('mounted', node.getBoundingClientRect());
}, []);
return <div ref={measureRef}>...</div>;

🤔 의사결정 기준

상황	useRef	useState
DOM 참조	✅	❌
렌더에 반영해야 함	❌	✅
렌더와 무관한 mutable	✅	❌
timer/AbortController 핸들	✅	❌
자식 imperative 메서드 노출	useImperativeHandle	❌

❌ 안티패턴

• ref.current 변경 후 화면 갱신 기대: ref 는 재렌더 trigger 안 함. forceUpdate 또는 state 사용.
• render 중 ref.current 읽기/쓰기: concurrent mode 에서 일관성 깨짐. effect 안에서.
• forwardRef 안 쓰고 props.ref 로 받기: React 18 에서 안 됨 (React 19 에서 ref prop 가능).
• 모든 mutable 데이터 ref 로: state 가 더 나음. ref 는 진짜 렌더 안 영향 줄 때.
• ref 가 callback 으로 받는 노드의 cleanup 안 함: callback ref 는 unmount 시 null 받음. 거기서 정리.

🤖 LLM 활용 힌트

• "DOM 측정/포커스/스크롤 = ref. 렌더 영향 = state" 강조.
• forwardRef 작성 시 imperative handle 의 메서드 시그니처 명확히.

🔗 관련 문서

• React_Custom_Hook_Patterns
• React_Controlled_vs_Uncontrolled