Manipular el DOM con Refs

Obtener una ref del nodo

Para acceder a un nodo DOM gestionado por React, primero importa el Hook useRef:

import { useRef } from 'react';

Luego, úsalo para declarar una ref dentro de tu componente

const myRef = useRef(null);

Finalmente, pasa la ref como el atributo ref a la etiqueta JSX en el que quieres obtener el nodo DOM:

<div ref={myRef}>

El Hook useRef devuelve un objeto con una sola propiedad llamada current. Inicialmente, myRef.current va a ser null. Cuando React cree un nodo DOM para este <div>, React pondrá una referencia a este nodo en myRef.current. Entonces podrás acceder a este nodo DOM desde tus controladores de eventos y usar las API de navegador integradas definidas en él.

// Puedes usar cualquier API de navegador, por ejemplo:
myRef.current.scrollIntoView();

Ejemplo: Enfocar el campo de texto input

En este ejemplo, hacer clic en el botón va a enfocar el input:

Para implementar esto:

1. Declara inputRef con el Hook useRef.
2. Pásalo como <input ref={inputRef}>. Esto le dice a React que coloque el nodo DOM <input> en inputRef.current.
3. En la función handleClick, lee el nodo input del DOM desde inputRef.current y llama a focus() en él con inputRef.current.focus().
4. Pasa el controlador de evento handleClick a <button> con onClick.

Mientras manipular el DOM es el caso de uso más común para las refs, el Hook useRef puede ser usado para almacenar otras cosas fuera de React, como las ID de temporizadores. De manera similar al estado, las refs permanecen entre renderizados. Las refs son como variables de estado que no desencadenan nuevos renderizados cuando las pones. Lee acerca de las refs en Referenciar valores con refs.

Ejemplo: Desplazarse a un elemento

Puedes tener más de una ref en un componente. En este ejemplo, hay un carrusel de tres imágenes. Cada botón centra una imagen al llamar al método del navegador scrollIntoView() en el nodo DOM correspondiente:

<ul>
  {items.map((item) => {
    // ¡No 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 el Map en el primer uso
      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) {
      // Add to the Map
      map.set(cat, node);
    } else {
      // Remove from the Map
      map.delete(cat);
    }
  }}
>

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

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

Accediendo a nodos DOM de otros componentes

Cuando colocas una ref en un componente integrado que devuelve de salida un elemento del navegador como <input />, React establecerá la propiedad current de esa ref al nodo DOM correspondiente (como el <input /> real del navegador)

Sin embargo, si intentas poner una ref en tu propio componente, como <MyInput />, por defecto tendrás null. Aquí hay un ejemplo demostrándolo. Nota como al hacer clic en el botón no enfoca el input.

Para ayudarte a notar el problema, React también mostrará un error en la consola.

Esto ocurre porque por defecto React no permite que un componente acceda a los nodos DOM de otros componentes. ¡Ni siquiera a sus propios hijos! Esto es intencionado. Las refs son una vía de escape que debe usarse con moderación. Manipular manualmente los nodos DOM de otro componente hace tu código aún más frágil.

En cambio, los componentes que quieran exponer sus nodos DOM tienen que optar por ese comportamiento. Un componente puede especificar que «reenvíe» su ref a uno de sus hijos. Aquí vemos como MyInput puede usar la API forwardRef:

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

Así es como funciona:

1. <MyInput ref={inputRef} /> le dice a React que coloque el nodo DOM correspondiente en inputRef.current. Sin embargo, depende del componente MyInput utilizarlo o no; por defecto no lo hace.
2. El componente MyInput es declarado usando forwardRef. Esto hace que pueda optar por recibir el inputRef como segundo argumento de ref la cual está declarada después de props.
3. MyInput por si mismo pasa la ref que recibió del <input> dentro de él.

Ahora al hacer clic en el botón para enfocar el input, funciona:

En diseño de sistemas, es un patrón común para componentes de bajo nivel como botones, inputs, etc. reenviar sus refs a sus nodos DOM. Por otro lado, los componentes de alto nivel como formularios, listas, o secciones de página, usualmente no suelen exponer sus nodos DOM para evitar dependencias accidentales de la estructura del DOM.

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

const MyInput = forwardRef((props, ref) => {
  const realInputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    // Solo expone focus y nada más
    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}>
        Enfocar el input
      </button>
    </>
  );
}

Cuando React adjunta las refs

En React, cada actualización está dividida en dos fases:

• Durante el renderizado, React llama a tus componentes para averiguar que debería estar en la pantalla.
• Durante la confirmación, React aplica los cambios a el DOM.

En general, no quieres acceder a las refs durante el renderizado. Eso va también para las refs que tienen nodos DOM. Durante el primer renderizado, los nodos DOM aún no han sido creados, entonces ref.current será null. Y durante el renderizado de actualizaciones, los nodos DOM aún no se han actualizado. Es muy temprano para leerlos.

React establece ref.current durante la confirmación. Antes de actualizar el DOM, React establece los valores afectados de ref.current a null. Después de actualizar el DOM, React inmediatamente los establece en los nodos DOM correspondientes.

Generalmente, vas a acceder a las refs desde los controladores de eventos. Si quieres hacer algo con una ref, pero no hay un evento en particular para hacerlo, es posible que necesites un Efecto. Discutiremos los Efectos en las 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}>
        Agregar
      </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}>
        Agregar
      </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)
  });
}

Mejores prácticas para la manipulación del DOM con refs

Las refs son una vía de escape. Sólo deberías usarlas cuando tengas que «salirte de React». Ejemplos comunes de esto incluyen la gestión del foco, la posición del scroll, o una llamada a las API del navegador que React no expone.

Si te limitas a acciones no destructivas como enfocar o desplazarte, no deberías encontrar ningún problema. Sin embargo, si intentas modificar el DOM manualmente, puedes arriesgarte a entrar en conflicto con los cambios que React está haciendo.

Para ilustrar este problema, este ejemplo incluye un mensaje de bienvenida y dos botones. El primer botón alterna su presencia usando renderizado condicional y estado, como normalmente lo harías en React. El segundo botón usa la API del DOM remove() para eliminarlo forzadamente del DOM fuera del control de React.

Intenta presionar «Alternar con setState» unas cuantas veces. El mensaje debe desaparecer y aparecer otra vez. Luego presiona «Eliminar del DOM». Esto lo eliminará forzadamente. Finalmente, presiona «Alternar con setState»:

Después de que hayas eliminado el elemento DOM, intentar usar setState para mostrarlo de nuevo provocará un fallo. Esto se debe a que has cambiado el DOM, y React no sabe cómo seguir gestionándolo correctamente.

Evita cambiar nodos DOM gestionados por React. Modificar, agregar hijos, o eliminar hijos de elementos que son gestionados por React pueden traer resultados inconsistentes visuales o fallos como el de arriba.

Sin embargo, esto no quiere decir que no puedas en absoluto. Requiere de cuidado. Puedes modificar de manera segura partes del DOM que React no tenga motivos para actualizar. Por ejemplo, si algún <div> siempre está vacío en el JSX, React no tendrá un motivo para tocar su lista de elementos hijos. Por lo tanto, es seguro agregar o eliminar manualmente elementos allí.