Manipulating the DOM with Refs

Obtendo uma ref para o nó

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

import { useRef } from 'react';

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

const myRef = useRef(null);

Finalmente, passe sua 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 criar 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 a partir dos seus manipuladores de eventos e usar as APIs do navegador integradas definidas nele.

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

Exemplo: Focando um campo de texto

Neste exemplo, clicar no botão focará no campo de 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ó DOM deste <input> em inputRef.current.
3. Na função handleClick, leia o nó DOM do input a partir 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 timers. De forma semelhante ao estado, as refs persistem entre as renderizações. Refs são como variáveis de estado que não disparam re-renderizações quando você as define. Leia sobre refs em Referenciando Valores com Refs.

Exemplo: Rolando para um elemento

Você pode ter mais de uma ref em um componente. Neste exemplo, há um carrossel de três imagens. Cada botão centraliza uma imagem chamando o método do navegador scrollIntoView() 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 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[8])}>Bella</button>
      </nav>
      <div>
        <ul>
          {catList.map((cat) => (
            <li
              key={cat.id}
              ref={(node) => {
                const map = getMap();
                map.set(cat, node);

                return () => {
                  map.delete(cat);
                };
              }}
            >
              <img src={cat.imageUrl} />
            </li>
          ))}
        </ul>
      </div>
    </>
  );
}

function setupCatList() {
  const catCount = 10;
  const catList = new Array(catCount)
  for (let i = 0; i < catCount; i++) {
    let imageUrl = '';
    if (i < 5) {
      imageUrl = "https://placecats.com/neo/320/240";
    } else if (i < 8) {
      imageUrl = "https://placecats.com/millie/320/240";
    } else {
      imageUrl = "https://placecats.com/bella/320/240";
    }
    catList[i] = {
      id: i,
      imageUrl,
    };
  }
  return catList;
}

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

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

Acessando nós DOM de outros componentes

Você pode passar refs de um componente pai para 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, uma ref é criada no componente pai, MyForm, e é passada para o componente filho, MyInput. MyInput então passa a ref para <input>. Como <input> é um componente integrado, o React define a propriedade .current da ref para o elemento DOM <input>.

A inputRef criada em MyForm agora aponta para o elemento DOM <input> retornado por MyInput. Um manipulador de clique criado em MyForm pode acessar inputRef e chamar focus() nele para focar em <input>.

import { useRef, useImperativeHandle } from "react";

function MyInput({ ref }) {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Expõe 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 as refs

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

• Durante o render, o React chama seus componentes para descobrir o que deve estar na tela.
• Durante o commit, o React aplica as 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 de atualizações, os nós DOM ainda não foram atualizados. Portanto, é 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.

Geralmente, você acessará refs a partir de manipuladores de eventos. Se você quiser fazer algo com uma ref, mas não houver um evento específico para isso, você 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 “válvula de escape”. Você só deve usá-las quando precisar “sair do React”. Exemplos comuns incluem gerenciar foco, posição de rolagem ou chamar APIs do navegador que o React não expõe.

Se você se ater a ações não destrutivas como focar e rolar, não deverá encontrar problemas. No entanto, se você tentar modificar o DOM manualmente, corre 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ê faria normalmente no React. O segundo botão usa a API DOM remove() para removê-lo forçosamente do DOM fora do controle do React.

Tente pressionar “Toggle with setState” algumas vezes. A mensagem deve desaparecer e reaparecer. Em seguida, pressione “Remove from the DOM”. Isso o removerá à força. Finalmente, pressione “Toggle with setState”:

Depois de remover manualmente o elemento DOM, tentar usar setState para mostrá-lo novamente levará a um erro. 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 erros como o acima.

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