Tipado de Refs

Receta

Tipea correctamente useRef para referencias de elementos DOM y contenedores de valores mutables. Entiende la diferencia entre refs de solo lectura del DOM y refs mutables, y cuándo usar cada una.

Ejemplo funcionando

// Ref de elemento DOM (current de solo lectura)
function TextInput() {
  const inputRef = useRef<HTMLInputElement>(null);
 
  const focusInput = () => {
    inputRef.current?.focus();
  };
 
  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={focusInput}>Enfocar entrada</button>
    </div>
  );
}

// Ref mutable (current escribible)
function Timer() {
  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
  const [count, setCount] = useState(0);
 
  const start = () => {
    if (intervalRef.current) return;
    intervalRef.current = setInterval(() => {
      setCount((c) => c + 1);
    }, 1000);
  };
 
  const stop = () => {
    if (intervalRef.current) {
      clearInterval(intervalRef.current);
      intervalRef.current = null;
    }
  };
 
  return (
    <div>
      <p>{count}</p>
      <button onClick={start}>Iniciar</button>
      <button onClick={stop}>Detener</button>
    </div>
  );
}

Análisis profundo

Cómo funciona

• useRef<HTMLInputElement>(null) crea un objeto ref con { current: HTMLInputElement | null }. Cuando se pasa a un atributo JSX ref, React administra el establecimiento de .current al nodo del DOM.
• En React 19, ref es una prop normal en lugar de un atributo especial. Los componentes de función pueden aceptar ref directamente en sus props sin forwardRef.
• Para refs mutables (almacenar temporizadores, valores anteriores, etc.), inicializa con null y tipea en consecuencia: useRef<NodeJS.Timeout | null>(null).
• La distinción entre refs de DOM y refs mutables es conceptual. Ambas usan useRef. La diferencia es si React administra .current (ref de DOM) o tú lo administras (ref mutable).

Variaciones

Almacenar valor anterior:

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => {
    ref.current = value;
  });
 
  return ref.current;
}

Patrón de callback de ref:

function MeasuredBox() {
  const [height, setHeight] = useState(0);
 
  const measuredRef = (node: HTMLDivElement | null) => {
    if (node) {
      setHeight(node.getBoundingClientRect().height);
    }
  };
 
  return (
    <div ref={measuredRef}>
      <p>Este cuadro tiene {height}px de alto</p>
    </div>
  );
}

Ref de elemento de video:

const videoRef = useRef<HTMLVideoElement>(null);
 
// Reproducir/pausar
const togglePlay = () => {
  if (videoRef.current?.paused) {
    videoRef.current.play();
  } else {
    videoRef.current?.pause();
  }
};

Notas de TypeScript

• Tipos comunes de ref de DOM: HTMLDivElement, HTMLInputElement, HTMLButtonElement, HTMLFormElement, HTMLCanvasElement, HTMLVideoElement, SVGSVGElement.
• ReturnType<typeof setInterval> es portátil entre entornos Node y navegador en lugar de codificar NodeJS.Timeout o number.
• En React 19, forwardRef ya no es necesario. Los componentes pueden aceptar ref como una prop normal: function Input({ ref }: { ref?: React.Ref<HTMLInputElement> }).

Trampa

• Acceder a inputRef.current sin una verificación de null generará un error en strictNullChecks. Siempre usa encadenamiento opcional (?.) o una guarda.
• Asignar a .current en una ref de DOM administrada por React no tiene efecto. React lo sobrescribe durante el renderizado.
• Usar useRef<HTMLInputElement>(null!) (aserción de no-null) elimina la necesidad de verificaciones de null pero oculta errores potenciales si la ref se accede antes del montaje.
• Los callbacks de ref se disparan con null cuando el componente se desmonta. Siempre maneja el caso null.

Alternativas

Preguntas frecuentes

const videoRef = useRef<HTMLVideoElement>(null);

function Input({ ref }: { ref?: React.Ref<HTMLInputElement> }) { ... }

Relacionado

• Tipado de eventos
• Tipado de Props
• Genéricos
• Conceptos básicos de TypeScript