Manipulando o DOM com Refs

Obtendo um ref para o nó

Para acessar um nó DOM gerenciada 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 para a qual você deseja obter o nó DOM:

<div ref={myRef}>

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

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

Exemplo: Focando uma entrada de texto

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

Para implementar isso:

1. Declare inputRef com o Hook useRef.
2. Passe-o como <input ref={inputRef}>. Isso informa ao React para colocar o nó DOM deste <input> em inputRef.current.
3. Na função handleClick, leia o nó DOM de entrada de inputRef.currente 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. Semelhante ao state, os refs permanecem entre as renderizações. Refs são como variáveis de state 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 único 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) {
      // Inicialize o Map no primeiro uso.
      itemsRef.current = new Map();
    }
    return itemsRef.current;
  }

  return (
    <>
      <nav>
        <button onClick={() => scrollToCat(catList[0])}>Neo</button>
        <button onClick={() => scrollToCat(catList[5])}>Millie</button>
        <button onClick={() => scrollToCat(catList[9])}>Bella</button>
      </nav>
      <div>
        <ul>
          {catList.map((cat) => (
            <li
              key={cat}
              ref={(node) => {
                const map = getMap();
                map.set(cat, node);

                return () => {
                  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();
    // Adicionar ao Map
    map.set(cat, node);

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

Acessando os nós DOM de outro componente

Você pode passar refs do componente pai para os componentes filhos assim como qualquer outra prop.

import { useRef } from 'react';

function MyInput({ ref }) {
  return <input ref={ref} />;
}

function MyForm() {
  const inputRef = useRef(null);
  return <MyInput ref={inputRef} />
}

No exemplo acima, um ref é criado no componente pai, MyForm, e é passado para o componente filho, MyInput. MyInput então passa o ref para <input>. Como <input> é um componente integrado, o React define a propriedade .current do ref para o elemento DOM <input>.

O inputRef criado em MyForm agora aponta para o elemento DOM <input> retornado por MyInput. Um manipulador de cliques criado em MyForm pode acessar inputRef e chamar focus() para definir o foco em <input>.

import { useRef, useImperativeHandle } from "react";

function MyInput({ ref }) {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Expor apenas o foco e nada mais
    focus() {
      realInputRef.current.focus();
    },
  }));
  return <input 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>
    </>
  );
}

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 commit, o React aplica alterações ao DOM.

Em geral, você não quer acessar refs durante a renderização. Isso vale também para refs que contêm nós DOM. 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. Então, é muito cedo para lê-los.

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

Normalmente, você acessará refs de manipuladores de eventos. Se você quiser fazer alguma coisa com um ref, mas não houver um evento específico para fazê-lo, pode precisar de um Effect. Discutiremos 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}>
        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)
  });
}

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

Refs são uma saída de emergência. Você só deve usá-los quando precisar “sair do React”. Exemplos comuns disso incluem o gerenciamento de foco, a posição da rolagem ou a chamada de APIs do navegador que o React não expõe.

Se você se ater a ações não destrutivas, como foco e rolagem, não deve encontrar nenhum problema. No entanto, se você tentar modificar o DOM manualmente, poderá correr o risco de entrar em conflito 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ê faria normalmente no React. O segundo botão usa a remove() DOM API 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 remover manualmente o elemento DOM, tentar usar setState para mostrá-lo novamente levará a uma falha. Isso ocorre porque você alterou o DOM e o React não sabe como continuar gerenciando-o corretamente.

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

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