Manipulating the DOM with Refsref로 DOM 조작하기

Getting a ref to the node노드에 대한 ref 가져오기

To access a DOM node managed by React, first, import the useRef Hook: React가 관리하는 DOM 노드에 접근하려면, 먼저 useRef 훅을 불러오세요:

import { useRef } from 'react';

Then, use it to declare a ref inside your component: 그런 다음 컴포넌트 내부에서 ref를 선언하세요:

const myRef = useRef(null);

Finally, pass your ref as the ref attribute to the JSX tag for which you want to get the DOM node: 마지막으로, DOM 노드를 가져올 JSX 태그에 ref 속성으로 참조를 전달하세요:

<div ref={myRef}>

The useRef Hook returns an object with a single property called current. Initially, myRef.current will be null. When React creates a DOM node for this <div>, React will put a reference to this node into myRef.current. You can then access this DOM node from your event handlers and use the built-in browser APIs defined on it. 이 useRef 훅은 current 라고 하는 프로퍼티가 포함된 객체를 반환합니다. 처음에는 myRef.current 는 null 이 될 것입니다. React가 이 <div>에 대한 DOM 노드를 생성하면, React는 이 노드에 대한 참조를 myRef.current에 넣습니다. 그런 다음 이벤트 핸들러에서 이 DOM 노드에 액세스하고 여기에 정의된 빌트인 브라우저 API를 사용할 수 있습니다.

// You can use any browser APIs, for example:
// 모든 브라우저 API를 사용할 수 있습니다. 예를 들어:
myRef.current.scrollIntoView();

Example: Focusing a text input예: 텍스트 input에 초점 맞추기

In this example, clicking the button will focus the input: 이 예제에서는 버튼을 클릭하면 input에 초점이 맞춰집니다:

To implement this: 이를 구현하려면:

1. Declare inputRef with the useRef Hook.
2. Pass it as <input ref={inputRef}>. This tells React to put this <input>’s DOM node into inputRef.current.
3. In the handleClick function, read the input DOM node from inputRef.current and call focus() on it with inputRef.current.focus().
4. Pass the handleClick event handler to <button> with onClick.

While DOM manipulation is the most common use case for refs, the useRef Hook can be used for storing other things outside React, like timer IDs. Similarly to state, refs remain between renders. Refs are like state variables that don’t trigger re-renders when you set them. Read about refs in Referencing Values with Refs. DOM 조작이 ref의 가장 일반적인 사용 사례이지만, useRef 훅은 timer ID와 같은 다른 것들을 React 외부에 저장하는 데 사용될 수 있습니다. state와 유사하게 ref는 렌더링 사이에 유지됩니다. ref는 state 변수와 비슷하지만 설정할 때 리렌더링을 촉발하지 않습니다. ref에 대한 자세한 내용은 Refs로 값 참조하기에서 읽어보세요.

Example: Scrolling to an element예: element로 스크롤하기

You can have more than a single ref in a component. In this example, there is a carousel of three images. Each button centers an image by calling the browser scrollIntoView() method on the corresponding DOM node: 컴포넌트를 ref를 하나 이상 포함할 수도 있습니다. 이 예시에는 세 개의 이미지로 구성된 캐러셀이 있습니다. 각 버튼은 DOM 노드에서 브라우저 scrollIntoView() 메서드를 호출하여 해당 이미지를 중앙에 배치합니다:

<ul>
  {items.map((item) => {
    // Doesn't work! 작동하지 않습니다!
    const ref = useRef(null);
    return <li ref={ref} />;
  })}
</ul>

import { useRef } from 'react';

export default function CatFriends() {
  const itemsRef = useRef(null);

  function scrollToId(itemId) {
    const map = getMap();
    const node = map.get(itemId);
    node.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest',
      inline: 'center'
    });
  }

  function getMap() {
    if (!itemsRef.current) {
      // Initialize the Map on first usage.
      itemsRef.current = new Map();
    }
    return itemsRef.current;
  }

  return (
    <>
      <nav>
        <button onClick={() => scrollToId(0)}>
          Tom
        </button>
        <button onClick={() => scrollToId(5)}>
          Maru
        </button>
        <button onClick={() => scrollToId(9)}>
          Jellylorum
        </button>
      </nav>
      <div>
        <ul>
          {catList.map(cat => (
            <li
              key={cat.id}
              ref={(node) => {
                const map = getMap();
                if (node) {
                  map.set(cat.id, node);
                } else {
                  map.delete(cat.id);
                }
              }}
            >
              <img
                src={cat.imageUrl}
                alt={'Cat #' + cat.id}
              />
            </li>
          ))}
        </ul>
      </div>
    </>
  );
}

const catList = [];
for (let i = 0; i < 10; i++) {
  catList.push({
    id: i,
    imageUrl: 'https://placekitten.com/250/200?image=' + i
  });
}

<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    if (node) {
      // Add to the Map
      map.set(cat.id, node);
    } else {
      // Remove from the Map
      map.delete(cat.id);
    }
  }}
>

Accessing another component’s DOM nodes다른 컴포넌트의 DOM 노드에 접근하기

When you put a ref on a built-in component that outputs a browser element like <input />, React will set that ref’s current property to the corresponding DOM node (such as the actual <input /> in the browser). <input />과 같은 브라우저 엘리먼트를 출력하는 빌트인 컴포넌트에 ref를 넣으면, React는 해당 ref의 current 프로퍼티를 해당 DOM 노드(예: 브라우저의 실제 <input />)로 설정합니다.

However, if you try to put a ref on your own component, like <MyInput />, by default you will get null. Here is an example demonstrating it. Notice how clicking the button does not focus the input: 그러나 <MyInput />과 같은 여러분이 만든 컴포넌트에 ref를 넣으려고 하면 기본적으로 null이 반환됩니다. 다음은 이를 보여주는 예시입니다. 버튼을 클릭해도 input에 초점이 맞춰지지 않는 것을 확인할 수 있습니다:

To help you notice the issue, React also prints an error to the console: 문제를 알아차리는 데 도움이 되도록 React는 콘솔에 오류를 출력하기도 합니다:

This happens because by default React does not let a component access the DOM nodes of other components. Not even for its own children! This is intentional. Refs are an escape hatch that should be used sparingly. Manually manipulating another component’s DOM nodes makes your code even more fragile. 이는 기본적으로 React가 컴포넌트가 다른 컴포넌트의 DOM 노드에 접근하는 것을 허용하지 않기 때문입니다. 심지어 자신의 자식에게도요! 이것은 의도적인 것입니다. ref는 탈출구이기 때문에 아껴서 사용해야 합니다. 다른 컴포넌트의 DOM 노드를 수동으로 조작하면 코드가 훨씬 더 취약해집니다.

Instead, components that want to expose their DOM nodes have to opt in to that behavior. A component can specify that it “forwards” its ref to one of its children. Here’s how MyInput can use the forwardRef API: 대신, DOM 노드를 노출하길 원하는 컴포넌트에 해당 동작을 설정해야 합니다. 컴포넌트는 자신의 ref를 자식 중 하나에 “전달”하도록 지정할 수 있습니다. MyInput이 forwardRef API를 사용하는 방법은 다음과 같습니다:

const MyInput = forwardRef((props, ref) => {
  return <input {...props} ref={ref} />;
});

This is how it works: 작동 방식은 다음과 같습니다:

1. <MyInput ref={inputRef} /> tells React to put the corresponding DOM node into inputRef.current. However, it’s up to the MyInput component to opt into that—by default, it doesn’t.
2. The MyInput component is declared using forwardRef. This opts it into receiving the inputRef from above as the second ref argument which is declared after props.
3. MyInput itself passes the ref it received to the <input> inside of it.

Now clicking the button to focus the input works: 이제 버튼을 클릭하면 input에 초점이 맞춰집니다:

In design systems, it is a common pattern for low-level components like buttons, inputs, and so on, to forward their refs to their DOM nodes. On the other hand, high-level components like forms, lists, or page sections usually won’t expose their DOM nodes to avoid accidental dependencies on the DOM structure. 디자인 시스템에서 버튼, 입력 등과 같은 저수준 컴포넌트는 해당 ref를 DOM 노드로 전달하는 것이 일반적인 패턴입니다. 반면 양식, 목록 또는 페이지 섹션과 같은 상위 수준 컴포넌트는 일반적으로 DOM 구조에 대한 우발적 의존성을 피하기 위해 해당 DOM 노드를 노출하지 않습니다.

import {
  forwardRef, 
  useRef, 
  useImperativeHandle
} from 'react';

const MyInput = forwardRef((props, ref) => {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Only expose focus and nothing else
    focus() {
      realInputRef.current.focus();
    },
  }));
  return <input {...props} ref={realInputRef} />;
});

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <MyInput ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

When React attaches the refsReact가 ref를 첨부할 때

In React, every update is split in two phases: React에서 모든 업데이트는 두 단계로 나뉩니다:

• During render, React calls your components to figure out what should be on the screen.
• During commit, React applies changes to the DOM.

In general, you don’t want to access refs during rendering. That goes for refs holding DOM nodes as well. During the first render, the DOM nodes have not yet been created, so ref.current will be null. And during the rendering of updates, the DOM nodes haven’t been updated yet. So it’s too early to read them. 일반적으로 렌더링 중에는 ref에 액세스하는 것을 원하지 않을 것입니다. DOM 노드를 보유하는 ref도 마찬가지입니다. 첫 번째 렌더링 중에는 DOM 노드가 아직 생성되지 않았으므로 ref.current는 null이 됩니다. 그리고 업데이트를 렌더링하는 동안에는 DOM 노드가 아직 업데이트되지 않았습니다. 따라서 이를 읽기에는 너무 이르죠.

React sets ref.current during the commit. Before updating the DOM, React sets the affected ref.current values to null. After updating the DOM, React immediately sets them to the corresponding DOM nodes. React는 커밋하는 동안에 ref.current를 설정합니다. React는 DOM이 업데이트 되기 전에는 ref.current의 값을 null로 설정하였다가, DOM이 업데이트된 직후 해당 DOM 노드로 다시 설정합니다.

Usually, you will access refs from event handlers. If you want to do something with a ref, but there is no particular event to do it in, you might need an Effect. We will discuss Effects on the next pages. 일반적으로 이벤트 핸들러에서 ref에 접근합니다. ref로 무언가를 하고 싶지만 그 작업을 수행할 특정 이벤트가 없다면, Effect가 필요할 수 있습니다. Effect에 대해서는 다음 페이지에서 설명하겠습니다.

import { useState, useRef } from 'react';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    setText('');
    setTodos([ ...todos, newTodo]);
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Add
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Todo #' + (i + 1)
  });
}

setTodos([ ...todos, newTodo]);
listRef.current.lastChild.scrollIntoView();

flushSync(() => {
  setTodos([ ...todos, newTodo]);
});
listRef.current.lastChild.scrollIntoView();

import { useState, useRef } from 'react';
import { flushSync } from 'react-dom';

export default function TodoList() {
  const listRef = useRef(null);
  const [text, setText] = useState('');
  const [todos, setTodos] = useState(
    initialTodos
  );

  function handleAdd() {
    const newTodo = { id: nextId++, text: text };
    flushSync(() => {
      setText('');
      setTodos([ ...todos, newTodo]);      
    });
    listRef.current.lastChild.scrollIntoView({
      behavior: 'smooth',
      block: 'nearest'
    });
  }

  return (
    <>
      <button onClick={handleAdd}>
        Add
      </button>
      <input
        value={text}
        onChange={e => setText(e.target.value)}
      />
      <ul ref={listRef}>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </>
  );
}

let nextId = 0;
let initialTodos = [];
for (let i = 0; i < 20; i++) {
  initialTodos.push({
    id: nextId++,
    text: 'Todo #' + (i + 1)
  });
}

Best practices for DOM manipulation with refsref를 이용한 DOM 조작 모범 사례

Refs are an escape hatch. You should only use them when you have to “step outside React”. Common examples of this include managing focus, scroll position, or calling browser APIs that React does not expose. Ref는 탈출구입니다. “React 외부로 나가야” 할 때만 사용해야 합니다. 일반적인 예로는 초점을 맞추거나, 스크롤 위치를 관리하거나 React가 노출하지 않는 브라우저 API를 호출하는 것이 있습니다.

If you stick to non-destructive actions like focusing and scrolling, you shouldn’t encounter any problems. However, if you try to modify the DOM manually, you can risk conflicting with the changes React is making. 포커스나 스크롤 같은 비파괴적 동작을 고수한다면 문제가 발생하지 않을 것입니다. 그러나 DOM을 수동으로 수정하려고 하면 React가 수행하는 변경 사항과 충돌할 위험이 있습니다.

To illustrate this problem, this example includes a welcome message and two buttons. The first button toggles its presence using conditional rendering and state, as you would usually do in React. The second button uses the remove() DOM API to forcefully remove it from the DOM outside of React’s control. 다음 예시에는 이 문제를 설명하기 위해 환영 메시지와 두 개의 버튼이 포함되어 있습니다. 첫 번째 버튼은 React에서 일반적으로 사용하는 것처럼 조건부 렌더링과 state를 사용하여 그 존재 여부를 전환합니다. 두 번째 버튼은 remove() DOM API를 사용하여 React가 제어할 수 없는 DOM에서 강제로 제거합니다.

Try pressing “Toggle with setState” a few times. The message should disappear and appear again. Then press “Remove from the DOM”. This will forcefully remove it. Finally, press “Toggle with setState”: “Toggle with setState”를 몇 번 눌러보세요. 메시지가 사라졌다가 다시 나타날 것입니다. 그런 다음 “Remove from the DOM”을 누르세요. 그러면 강제로 제거될 것입니다. 마지막으로 “Toggle with setState”를 눌러보세요:

After you’ve manually removed the DOM element, trying to use setState to show it again will lead to a crash. This is because you’ve changed the DOM, and React doesn’t know how to continue managing it correctly. DOM 엘리먼트를 수동으로 제거한 후 setState를 사용하여 다시 표시하려고 하면 충돌이 발생합니다. 이는 사용자가 DOM을 변경했고 React가 이를 계속 올바르게 관리하는 방법을 모르기 때문입니다.

Avoid changing DOM nodes managed by React. Modifying, adding children to, or removing children from elements that are managed by React can lead to inconsistent visual results or crashes like above. React가 관리하는 DOM 노드를 변경하지 마세요. React가 관리하는 요소를 수정하거나, 자식을 추가하거나 제거하면, 위와 같이 일관성 없는 시각적 결과나 충돌이 발생할 수 있습니다.

However, this doesn’t mean that you can’t do it at all. It requires caution. You can safely modify parts of the DOM that React has no reason to update. For example, if some <div> is always empty in the JSX, React won’t have a reason to touch its children list. Therefore, it is safe to manually add or remove elements there. 그렇다고 전혀 할 수 없다는 건 아니고, 주의가 필요하다는 의미입니다. React가 업데이트할 이유가 없는 DOM의 일부는 안전하게 수정할 수 있습니다. 예를 들어, JSX에서 일부 <div>가 항상 비어 있는 경우, React는 그 자식 목록을 건드릴 이유가 없습니다. 따라서 수동으로 요소를 추가하거나 제거하더라도 안전합니다.