Tipando Refs

Receita

Tipar useRef corretamente para referências de elementos DOM e contêineres de valores mutáveis. Entender a diferença entre refs DOM somente leitura e refs mutáveis, e quando usar cada uma.

Exemplo de Trabalho

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

// Ref mutável (gravável .current)
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}>Parar</button>
    </div>
  );
}

Análise Profunda

Como Funciona

• useRef<HTMLInputElement>(null) cria um objeto ref com { current: HTMLInputElement | null }. Quando passado para um atributo ref JSX, o React gerencia a definição de .current para o nó DOM.
• No React 19, ref é uma prop regular em vez de um atributo especial. Componentes de função podem aceitar ref diretamente em suas props sem forwardRef.
• Para refs mutáveis (armazenando timers, valores anteriores, etc.), inicialize com null e tipifique de acordo: useRef<NodeJS.Timeout | null>(null).
• A distinção entre refs DOM e refs mutáveis é conceitual. Ambas usam useRef. A diferença é se o React gerencia .current (ref DOM) ou você o gerencia sozinho (ref mutável).

Variações

Armazenando o valor anterior:

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

Padrão 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>Esta caixa tem {height}px de altura</p>
    </div>
  );
}

Ref de elemento de vídeo:

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

Notas do TypeScript

• Tipos comuns de ref DOM: HTMLDivElement, HTMLInputElement, HTMLButtonElement, HTMLFormElement, HTMLCanvasElement, HTMLVideoElement, SVGSVGElement.
• ReturnType<typeof setInterval> é portátil entre ambientes Node e navegador em vez de codificar NodeJS.Timeout ou number.
• No React 19, forwardRef não é mais necessário. Componentes podem aceitar ref como uma prop regular: function Input({ ref }: { ref?: React.Ref<HTMLInputElement> }).

Armadilhas

• Acessar inputRef.current sem uma verificação de nulo resultará em erro sob strictNullChecks. Sempre use encadeamento opcional (?.) ou uma guarda.
• Atribuir a .current em uma ref DOM gerenciada pelo React não tem efeito. O React a sobrescreve durante a renderização.
• Usar useRef<HTMLInputElement>(null!) (asserção não nula) remove a necessidade de verificações de nulo, mas oculta bugs potenciais se a ref for acessada antes da montagem.
• Callbacks de ref são disparados com null quando o componente é desmontado. Sempre trate o caso null.

Alternativas

FAQs

const videoRef = useRef<HTMLVideoElement>(null);

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

Relacionados

• Tipando Eventos
• Tipando Props
• Generics
• Noções Básicas de TypeScript