<div id="readability-page-1" class="page"><div>
 <div id="SE-a8ddfa26-2c4e-4c4e-92d4-f5c20727ef39">
 부모가 자식 컴포넌트에 ref를 넘겨 그 DOM 노드에 접근하는 법을 배웠습니다(React 19부터 ref는 일반 prop이죠). 그런데 자식이 부모에게 DOM 노드 전체가 아니라, 딱 필요한 메서드 몇 개만 골라서 노출하고 싶을 때가 있습니다. 그때 쓰는 게 useImperativeHandle입니다. 자주 쓰는 도구는 아니지만, 알아두면 "이럴 땐 이거"가 분명해집니다.
​
​
문제 — DOM 노드를 통째로 넘기고 싶지 않다
&lt;input&gt;을 감싼 커스텀 컴포넌트 FancyInput을 만들었다고 합시다. 부모는 "이 입력창에 포커스를 주거나, 내용을 비우고" 싶어 합니다. 부모에게 &lt;input&gt; DOM 노드를 그대로 넘기면 되긴 합니다. 하지만 그러면 부모가 &lt;input&gt;의 모든 것(value 조작, style 변경 등 무엇이든)을 만질 수 있게 됩니다. 내부 구현이 통째로 노출되는 거죠.
​
대신 "이 컴포넌트로 할 수 있는 일은 focus()와 clear()뿐"이라고 제한된 API만 깔끔하게 노출하고 싶습니다. 그게 useImperativeHandle이 하는 일입니다. 부모가 ref로 받게 될 값을 DOM 노드가 아니라 내가 정의한 객체로 바꿔주는 거죠.
​
​
사용법 — 부모에게 줄 핸들을 직접 정의한다
useImperativeHandle(ref, () =&gt; 핸들객체) 형태입니다. 부모가 넘긴 ref에, DOM 노드 대신 내가 만든 핸들 객체를 연결합니다.

 </div> <div id="SE-d452ca1f-3279-40c3-937a-b4bb60e2ff31">
 import { useRef, useImperativeHandle } from 'react';

// 부모에게 노출할 API의 타입
type FancyInputHandle = {
 focus: () =&gt; void;
 clear: () =&gt; void;
};

// React 19: ref를 일반 prop으로 받는다 (forwardRef 불필요)
function FancyInput({ ref }: { ref?: React.Ref&lt;FancyInputHandle&gt; }) {
 const inputRef = useRef&lt;HTMLInputElement&gt;(null); // 진짜 input은 내부에 숨긴다

 // 부모가 ref로 받을 값을 "이 두 메서드만 있는 객체"로 정의
 useImperativeHandle(ref, () =&gt; ({
 focus() {
 inputRef.current?.focus();
 },
 clear() {
 if (inputRef.current) inputRef.current.value = '';
 },
 }));

 return &lt;input ref={inputRef} className="fancy" /&gt;;
}
 </div> <div id="SE-1259af6f-6e09-475e-bed0-84a7180400e5">
 function Form() {
 const fancyRef = useRef&lt;FancyInputHandle&gt;(null);

 return (
 &lt;div&gt;
 &lt;FancyInput ref={fancyRef} /&gt;
 &lt;button onClick={() =&gt; fancyRef.current?.focus()}&gt;포커스&lt;/button&gt;
 &lt;button onClick={() =&gt; fancyRef.current?.clear()}&gt;지우기&lt;/button&gt;
 &lt;/div&gt;
 );
}
 </div> <div id="SE-b8d67a62-f5c7-4279-b567-ef69bf04f3c1">
 부모는 fancyRef.current.focus()와 .clear()만 호출할 수 있습니다. 진짜 &lt;input&gt; DOM 노드는 FancyInput 안에 숨겨져 있어서, 부모가 직접 만질 수 없죠. 노출 범위를 컴포넌트가 통제하는 겁니다.
 </div> <div id="SE-1ace14b1-b444-4b86-8d17-2efddd327cb9">
 언제 쓰나 — 드물게, 명령형이 꼭 필요할 때만
 </div> <div id="SE-a31e6578-f37e-4a95-be39-f84396efa2e7">
 ​
react.dev도 "거의 쓸 일이 없다(rarely used)"고 명시하는 훅입니다. 이유는 이 시리즈 내내 강조한 원칙 때문입니다. React는 선언적이 기본이고, 가능하면 props로 표현해야 합니다.
​
<ul><li>"입력창을 비활성화한다" → disabled prop으로. (명령형 핸들 필요 없음)
</li><li>"값을 보여준다" → value prop으로.
</li></ul>​
그럼 useImperativeHandle은 언제? props로는 표현하기 어려운, 본질적으로 "명령형"인 동작일 때입니다.
​
<ul><li>focus(), scrollIntoView() — "지금 이 순간 포커스를 줘/스크롤해"
</li><li>비디오 플레이어의 play(), pause()
</li><li>애니메이션 start() 등
</li></ul>​
이런 건 "상태"가 아니라 "행동"이라, prop으로 선언하기 어색합니다. 이때만 명령형 핸들을 꺼냅니다. 7장에서 이벤트를, 16장에서 Effect를 다룰 때처럼, "선언적으로 안 되는 것만 명령형으로"가 원칙입니다.
​
노출은 최소한으로. 핸들에는 부모가 정말 필요로 하는 메서드만 담으세요. "혹시 몰라서" DOM 노드를 통째로 노출하거나 메서드를 잔뜩 여는 건, 컴포넌트의 경계를 무너뜨립니다. 적게 노출할수록 그 컴포넌트는 바꾸기 쉬워집니다.

 </div> <div id="SE-fc7ba54d-a391-4a2a-b086-f6fb021a93a1">
 ​
<ul><li>useImperativeHandle(ref, () =&gt; 핸들)은 부모가 ref로 받을 값을 DOM 노드 대신 내가 정의한 객체로 바꾼다.
</li><li>덕분에 자식은 제한된 명령형 API(focus·clear 등)만 노출하고, 내부 DOM은 숨길 수 있다. 노출 범위를 통제한다.
</li><li>React 19에서는 ref가 일반 prop이라 forwardRef 없이 바로 받는다.
</li><li>드물게 쓴다. 기본은 선언적(props). focus·scroll·play처럼 본질적으로 명령형인 행동에만 쓴다.
</li><li>핸들은 최소한으로 노출한다. 적게 열수록 컴포넌트가 견고하다.
</li></ul>​
다음 챕터에서는 앱을 빠르게 띄우는 핵심 기법, 코드 분할(React.lazy + Suspense)을 다룹니다. 처음부터 모든 코드를 내려받지 않고, 필요한 순간에 나눠 불러오는 방법입니다. 이전에 맛만 본 Suspense도 여기서 본격적으로 등장합니다.

 </div> <div id="SE-15cade27-e5f5-4f28-a3a0-9b939ca8b56e">
 ​
<ul><li>useImperativeHandle — React 공식 문서 (확인: 2026-06-24)
</li><li>Manipulating the DOM with Refs — React 공식 문서 (확인: 2026-06-24)
</li></ul>
 </div> </div></div>

개발하는 기획자. 기획하는 개발자.

부모가 자식 컴포넌트에 ref를 넘겨 그 DOM 노드에 접근하는 법을 배웠습니다(React 19부터 ref는 일반 prop이죠). 그런데 자식이 부모에게 DOM 노드 전체가 아니라, 딱 필요한 메서드 몇 개만 골라서 노출하고 싶을 때가 있습니다. 그때 쓰는 게 useImperativeHandle입니다. 자주 쓰는 도구는 아니지만, 알아두면 "이럴 땐 이거"가 분명해집니다. 문제 — DOM 노드를 통째로 넘기고 싶지 않다 을 감싼 커스텀 컴포넌트 FancyInput을 만들었다고 합시다. 부모는 "이 입력창에 포커스를 주거나, 내용을 비우고" 싶어 합니다. 부모에게  DOM 노드를 그대로 넘기면 되긴 합니다. 하지만 그러면 부모.......

useImperativeHandle — 자식이 부모에게 노출하는 명령형 핸들

댓글