Manipulando o DOM com Refs

Obtendo um ref para o nó

Para acessar um nó do DOM gerenciado pelo React, primeiro importe o Hook useRef:

import { useRef } from 'react';

Em seguida, use-o para declarar um ref dentro do seu componente:

const myRef = useRef(null);

Finalmente, passe seu ref como o atributo ref para a tag JSX da qual você deseja obter o nó do DOM:

<div ref={myRef}>

O Hook useRef retorna um objeto com uma única propriedade chamada current. Inicialmente, myRef.current será null. Quando o React criar um nó do DOM para este <div>, o React colocará uma referência a este nó em myRef.current. Você poderá então acessar este nó do DOM de seus manipuladores de eventos e usar as APIs de navegador integradas definidas nele.

// Você pode usar qualquer API de navegador, por exemplo:
myRef.current.scrollIntoView();

Exemplo: Focando um campo de texto

Neste exemplo, clicar no botão irá focar a entrada:

Para implementar isso:

1. Declare inputRef com o Hook useRef.
2. Passe-o como <input ref={inputRef}>. Isso diz ao React para colocar o nó do DOM deste <input> em inputRef.current.
3. Na função handleClick, leia o nó do DOM da entrada de inputRef.current e chame focus() nele com inputRef.current.focus().
4. Passe o manipulador de eventos handleClick para <button> com onClick.

Embora a manipulação do DOM seja o caso de uso mais comum para refs, o Hook useRef pode ser usado para armazenar outras coisas fora do React, como IDs de temporizador. Assim como o estado, os refs permanecem entre as renderizações. Os refs são como variáveis de estado que não acionam novas renderizações quando você as define. Leia sobre refs em Referenciando Valores com Refs.

Exemplo: Rolando para um elemento

Você pode ter mais de um ref em um componente. Neste exemplo, há um carrossel de três imagens. Cada botão centraliza uma imagem chamando o método scrollIntoView() do navegador no nó DOM correspondente:

<ul>
  {items.map((item) => {
    // Não funciona!
    const ref = useRef(null);
    return <li ref={ref} />;
  })}
</ul>

import { useRef, useState } from "react";

export default function CatFriends() {
  const itemsRef = useRef(null);
  const [catList, setCatList] = useState(setupCatList);

  function scrollToCat(cat) {
    const map = getMap();
    const node = map.get(cat);
    node.scrollIntoView({
      behavior: "smooth",
      block: "nearest",
      inline: "center",
    });
  }

  function getMap() {
    if (!itemsRef.current) {
      // Inicializa o Map na primeira utilização.
      itemsRef.current = new Map();
    }
    return itemsRef.current;
  }

  return (
    <>
      <nav>
        <button onClick={() => scrollToCat(catList[0])}>Tom</button>
        <button onClick={() => scrollToCat(catList[5])}>Maru</button>
        <button onClick={() => scrollToCat(catList[9])}>Jellylorum</button>
      </nav>
      <div>
        <ul>
          {catList.map((cat) => (
            <li
              key={cat}
              ref={(node) => {
                const map = getMap();
                if (node) {
                  map.set(cat, node);
                } else {
                  map.delete(cat);
                }
              }}
            >
              <img src={cat} />
            </li>
          ))}
        </ul>
      </div>
    </>
  );
}

function setupCatList() {
  const catList = [];
  for (let i = 0; i < 10; i++) {
    catList.push("https://loremflickr.com/320/240/cat?lock=" + i);
  }

  return catList;
}

<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    if (node) {
      // Adiciona ao Map
      map.set(cat, node);
    } else {
      // Remove do Map
      map.delete(cat);
    }
  }}
>

<li
  key={cat.id}
  ref={node => {
    const map = getMap();
    // Adiciona ao Map
    map.set(cat, node);

    return () => {
      // Remove do Map
      map.delete(cat);
    };
  }}
>

Acessando os nós DOM de outro componente

Quando você coloca um ref em um componente embutido que gera um elemento de navegador como <input />, o React definirá a propriedade current desse ref para o nó DOM correspondente (como o <input /> real no navegador).

No entanto, se você tentar colocar um ref em seu próprio componente, como <MyInput />, por padrão você obterá null. Aqui está um exemplo demonstrando isso. Note como clicar no botão não foca a entrada:

Para ajudá-lo a notar o problema, o React também imprime um erro no console:

Isso acontece porque, por padrão, o React não permite que um componente acesse os nós DOM de outros componentes. Nem mesmo para seus próprios filhos! Isso é intencional. Os refs são uma escapatória que deve ser usada com moderação. Manipular manualmente os nós DOM de outro componente torna seu código ainda mais frágil.

Em vez disso, componentes que querem expor seus nós DOM devem optar por esse comportamento. Um componente pode especificar que “encaminha” seu ref para um de seus filhos. Aqui está como MyInput pode usar a API forwardRef:

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

Assim funciona:

1. <MyInput ref={inputRef} /> diz ao React para colocar o nó DOM correspondente em inputRef.current. No entanto, cabe ao componente MyInput optar por isso—por padrão, ele não faz.
2. O componente MyInput é declarado usando forwardRef. Isso o opta para receber o inputRef de cima como o segundo argumento ref que é declarado após props.
3. O MyInput em si passa o ref que recebeu para o <input> dentro dele.

Agora, clicar no botão para focar a entrada funciona:

Em sistemas de design, é um padrão comum que componentes de baixo nível, como botões, entradas e assim por diante, encaminhem seus refs para seus nós DOM. Por outro lado, componentes de alto nível, como formulários, listas ou seções de página, geralmente não expõem seus nós DOM para evitar dependências acidentais na estrutura DOM.

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

const MyInput = forwardRef((props, ref) => {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Apenas expõe foco e mais nada
    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}>
        Focar na entrada
      </button>
    </>
  );
}

Quando o React anexa os refs

No React, cada atualização é dividida em duas fases:

• Durante a renderização, o React chama seus componentes para descobrir o que deve estar na tela.
• Durante o compromisso, o React aplica as alterações ao DOM.

Em geral, você não quer acessar refs durante a renderização. Isso se aplica a refs que contêm nós DOM também. Durante a primeira renderização, os nós DOM ainda não foram criados, então ref.current será null. E durante a renderização das atualizações, os nós DOM ainda não foram atualizados. Portanto, é cedo demais para lê-los.

O React define ref.current durante o compromisso. Antes de atualizar o DOM, o React define os valores afetados de ref.current como null. Após atualizar o DOM, o React imediatamente os define para os nós DOM correspondentes.

Geralmente, você acessará refs a partir de manipuladores de eventos. Se você quiser fazer algo com um ref, mas não houver um evento específico para fazê-lo, pode precisar de um Effect. Vamos discutir Effects nas próximas páginas.

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}>
        Adicionar
      </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: 'Tarefa #' + (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}>
        Adicionar
      </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: 'Tarefa #' + (i + 1)
  });
}

Melhores práticas para manipulação do DOM com refs

Refs são uma escapatória. Você só deve usá-los quando precisar “sair do React”. Exemplos comuns disso incluem gerenciar foco, posição de rolagem, ou chamar APIs de navegador que o React não expõe.

Se você se limitar a ações não destrutivas, como focar e rolar, não deverá encontrar problemas. No entanto, se você tentar modificar o DOM manualmente, pode correr o risco de conflitar com as alterações que o React está fazendo.

Para ilustrar esse problema, este exemplo inclui uma mensagem de boas-vindas e dois botões. O primeiro botão alterna sua presença usando renderização condicional e estado, como você normalmente faria no React. O segundo botão usa a API DOM remove() para removê-lo à força do DOM fora do controle do React.

Tente pressionar “Alternar com setState” algumas vezes. A mensagem deve desaparecer e aparecer novamente. Em seguida, pressione “Remover do DOM”. Isso o removerá à força. Finalmente, pressione “Alternar com setState”:

Depois de você remover manualmente o elemento DOM, tentar usar setState para mostrá-lo novamente resultará em uma falha. Isso acontece porque você mudou o DOM, e o React não sabe como continuar gerenciando-o corretamente.

Evite mudar nós DOM gerenciados pelo React. Modificar, adicionar filhos a, ou remover filhos de elementos que são gerenciados pelo React pode levar a resultados visuais inconsistentes ou falhas como a acima.

No entanto, isso não significa que você não possa fazê-lo. Isso requer cautela. Você pode modificar partes do DOM que o React não tem razão para atualizar com segurança. Por exemplo, se algum <div> estiver sempre vazio no JSX, o React não terá razão para tocar em sua lista de filhos. Portanto, é seguro adicionar ou remover elementos manualmente lá.