Ref ve DOM

Ref Nedir

Ref, render'lar arasında saklanan ama değiştiğinde render tetiklemeyen bir kutudur. useRef bir obje döndürür; değer current alanındadır.¹

React dokümanı ref'i bir kaçış kapısı olarak tanımlar: React dışındaki bir şeyle konuşurken kullanılır. Uygulamanın mantığı ref'lerden akıyorsa yaklaşımı gözden geçirin.¹

DOM Elemanına Erişmek

Çoğu iş deklaratif yapılır, ama bazı şeylerin JSX karşılığı yoktur: odaklanmak, bir yere kaydırmak, video oynatmak, eleman ölçmek. Bunun için ref'i JSX'teki ref attribute'una verirsiniz; React DOM elemanını current'a koyar.³

import { useRef } from "react";

export function SearchBox() {
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <>
      <input ref={inputRef} type="search" placeholder="Ürün ara" />
      <button onClick={() => inputRef.current?.focus()}>Ara</button>
    </>
  );
}

current ilk render'da null'dır; React ref'i commit sırasında, DOM'u güncelledikten sonra bağlar. Bu yüzden ref'lere event handler'larda ya da Effect'lerde erişilir.³

Kendi Component'inize ref Vermek

React 19'dan beri ref fonksiyon component'lerde sıradan bir prop'tur. forwardRef artık gerekmez ve ileride kaldırılacak.⁴

function TextField({ ref, ...props }: React.ComponentProps<"input">) {
  return <input ref={ref} className="text-field" {...props} />;
}

<TextField ref={inputRef} placeholder="E-posta" />;

Ebeveynin DOM elemanının tamamına değil, yalnızca birkaç metoda erişmesini istiyorsanız useImperativeHandle ile küçük bir API açabilirsiniz. Bunu seyrek kullanın; open() ve close() gibi metotlar yerine isOpen gibi bir prop çoğu zaman daha iyidir.³⁵

Ref Callback ve Cleanup

ref'e obje yerine bir fonksiyon da verebilirsiniz. React elemanı DOM'a ekleyince fonksiyonu elemanla çağırır. React 19'da bu fonksiyon bir cleanup döndürebilir; eleman kaldırılınca çağrılır.⁶⁴

function measure(node: HTMLElement) {
  const observer = new ResizeObserver(([entry]) => {
    console.log("Kart genişliği:", entry.contentRect.width);
  });
  observer.observe(node);
  return () => observer.disconnect();
}

<article ref={measure}>...</article>;

TkDodo'nun ref callback ile Effect arasındaki kuralları:⁷

• DOM elemanına ihtiyacınız varsa ref callback tercih edin; useRef + useEffect'ten kısadır ve ebeveynin değil, elemanın render'ına bağlıdır. Fonksiyon component'e bağlı değilse yukarıdaki gibi component dışına taşıyın; her render'da yeniden oluşmaz.

• Elemanla ilgisi olmayan bir yan etki (örneğin document.title) için ref kullanmayın; Effect daha anlaşılırdır.

• Asenkron işler için ikisi de değil; veri çekme kütüphanesi.

Strict Mode, ref callback'leri de development'ta bir kez fazladan kurup söker; cleanup eksikse burada görürsünüz.⁶

Fragment Ref'leri

React 19.3 ile <Fragment>'e ref verilebiliyor. Sarmalayıcı bir <div> eklemeden, bir component'in render ettiği kardeş elemanların hepsiyle grup olarak çalışırsınız. Dönen FragmentInstance odak (focus, focusLast, blur), event listener ekleme ve IntersectionObserver/ResizeObserver bağlama gibi metotlar sunar.⁸⁹

import { Fragment, useEffect, useRef } from "react";

function FocusTrap({ children }: { children: React.ReactNode }) {
  const fragmentRef = useRef<React.FragmentInstance>(null);

  useEffect(() => {
    fragmentRef.current?.focus(); // ilk odaklanabilir çocuğa odaklan
  }, []);

  return <Fragment ref={fragmentRef}>{children}</Fragment>;
}

Bu özellikle elinizde olmayan component'lere (bir kütüphanenin listesi gibi) davranış eklerken işe yarar; component'in iç yapısını değiştirmeniz gerekmez.⁸ Odak yönetiminin erişilebilirlik tarafı Klavye ve odak yönetimi dersinde.

Portal

Modal, tooltip ve toast gibi elemanlar görsel olarak sayfanın en üstünde durmalıdır, ama component ağacında onları açan component'in yanında yaşar. createPortal, JSX'i DOM'da başka bir yere (genellikle document.body) render eder; event'ler ve context React ağacındaki yerine göre çalışmaya devam eder.¹⁰ Basit diyaloglar için önce yerleşik <dialog> elemanına bakın; HTML dersi anlatıyor.

Kendin Dene

• SearchBox'a sayfa açılınca input'a odaklanma ekleyin. Önce useEffect ile, sonra ref callback ile yazın.

• Bir ürün kartının genişliğini ResizeObserver ile ölçen ref callback'i yazın; cleanup'ı silip kartı birkaç kez gizleyip gösterin.

• Render sırasında inputRef.current?.value'yu ekrana basmayı deneyin ve lint'in uyarısını okuyun.

• Bir listeyi saran <div>'i kaldırıp yerine Fragment ref'i ile "görünür olunca logla" davranışı ekleyin.

Detaylı Öğrenmek İçin

• Resmi doküman: "Referencing Values with Refs" ve "Manipulating the DOM with Refs"; ikisi birlikte ref konusunun tamamı.¹³

• Yazı: TkDodo'nun ref callback'leri React 19 ve compiler ile yeniden değerlendirdiği yazı.⁷

• Resmi doküman: React 19.3 duyurusunun Fragment Refs bölümü; InView örneği.⁸