Controlled ve uncontrolled formlar

Değeri Kim Tutuyor?

Bir <input>'a yazılan metin bir yerde saklanır. Bu derste iki seçenek var:¹²

Josh W. Comeau farkı şöyle özetler: React varsayılan olarak form alanına karışmaz; alan uncontrolled'dır. value verdiğiniz anda React değeri yönetmeye başlar ve alan controlled olur.²

Uncontrolled: DOM'a Bırakmak

En basit form state tutmaz. Değerler gönderim anında FormData ile okunur. Her alanın bir name'i olmalı; FormData alanları adıyla toplar:³⁴

export function NewsletterForm() {
  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    const email = String(formData.get("email") ?? "");
    subscribe(email);
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="email">E-posta</label>
      <input id="email" name="email" type="email" defaultValue="" />
      <button>Abone ol</button>
    </form>
  );
}

FormData.get her zaman string, File ya da null döndürür. Sayı beklediğiniz alan da metin gelir; dönüştürmek ve doğrulamak sizin işinizdir.⁴ Bu yüzden sunucuya giden her formda bir şema kullanacaksınız (bkz. Zod ile şema ve doğrulama).

React 19'da action prop'una fonksiyon da verebilirsiniz. Fonksiyon FormData'yı doğrudan alır; preventDefault gerekmez:³

<form action={(formData) => subscribe(String(formData.get("email") ?? ""))}>

action ile gönderilen form, işlem başarıyla bitince uncontrolled alanları sıfırlar. Tarayıcının kendi davranışı da budur. Hata durumunda kullanıcının yazdıklarını korumak için ne yapacağınız Server Actions ile form dersinde.⁵

Controlled: State'e Bağlamak

Alanın değeri state'ten gelir; her tuşta onChange state'i günceller ve React alanı yeni değerle çizer:¹

export function SearchBox() {
  const [query, setQuery] = useState("");

  return (
    <>
      <label htmlFor="search">Ara</label>
      <input id="search" value={query} onChange={(event) => setQuery(event.target.value)} />
      <p>{query.length} karakter</p>
    </>
  );
}

Değer her an elinizde olduğu için yazarken arayüzü değiştirmek kolaydır: karakter sayacı, canlı filtre, bir alana göre başka alanı açmak. Bedeli, state'in sahibi component'in her tuşta yeniden render olmasıdır. Küçük bir formda fark edilmez; onlarca alanlı ve ağır component'li bir formda yazarken takılma hissedilir.

Yaygın Hatalar

React dokümanı controlled alanlarla ilgili üç uyarıyı ayrıca anlatır:¹

• value var, onChange yok. Alan salt okunur olur, kullanıcı yazamaz. React konsolda uyarır. Gerçekten salt okunursa readOnly verin; değilse onChange ekleyin ya da defaultValue'ya geçin.

• value={undefined} ile başlamak. Başlangıçta undefined olan alan uncontrolled sayılır; sonra bir değer gelince controlled olur ve React "uncontrolled'dan controlled'a geçiş" uyarısı verir. Metin alanlarını "" ile başlatın; null da vermeyin.

• Checkbox'ta value. Checkbox ve radio için durum checked ile kontrol edilir; value gönderilen değerdir.

Josh W. Comeau select için de aynı kuralı hatırlatır: başlangıç değeri seçeneklerden biriyle eşleşmelidir.²

Tarayıcının Doğrulaması

required, type="email", minLength ve pattern tarayıcıya ücretsiz doğrulama verir. Ama mesajlar tarayıcıya göre değişir, tasarıma uymaz ve ekran okuyucularla iyi çalışmaz. Adrian Roselli testlerinde alanın odak alır almaz "geçersiz" okunduğunu, desenin hiç açıklanmadığını ve alan düzelince bunun duyurulmadığını gösterir. Önerisi kendi doğrulamanızı yazmaktır.⁶ GOV.UK Design System da novalidate ile tarayıcı doğrulamasını kapatıp kendi hata mesajlarını göstermeyi önerir.⁷

<form novalidate>

novalidate yalnızca tarayıcının balonlarını kapatır. type="email" mobil klavyeyi değiştirmeye, autocomplete otomatik doldurmaya devam eder. Hata mesajlarını nasıl göstereceğiniz Hata gösterimi ve erişilebilirlik dersinde.

Form Kütüphanesi Neden?

İki alanlı bir formu iki yaklaşımla da elle yazabilirsiniz. Gerçek formlarda şunlar birikir: her alan için hata state'i, "alana dokunuldu mu", gönderiliyor mu, ilk değerden değişti mi, ilk hatalı alana odaklanmak, sunucudan gelen hatayı alana yazmak.

React Hook Form uncontrolled yaklaşımı temel alır: alanlara ref ile bağlanır, değeri DOM'dan okur ve yalnızca gereken component'i render eder.⁸ Kendi bileşeni value/onChange isteyen bir tarih seçici gibi controlled alanlar için de Controller sunar (bkz. Dinamik alanlar ve çok adımlı formlar).

Ne Zaman Hangisi

Kendin Dene

• Bülten formunu uncontrolled yazın, console.log(Object.fromEntries(formData)) ile gelen nesneye bakın. Yaş alanı ekleyin; tipi ne?

• Arama kutusunu useState("") yerine useState<string>() ile başlatın ve bir şey yazın. Konsolda ne çıkıyor?

• value verip onChange'i silin. Alana yazabiliyor musunuz?

• Formu novalidate olmadan, required ve type="email" ile gönderin. Sonra bir ekran okuyucuyla (VoiceOver, NVDA) deneyin.

Detaylı Öğrenmek İçin

• Resmi doküman: React, "<input>"; controlled alan, defaultValue ve sık yapılan hatalar.¹

• Yazı: Josh W. Comeau, "Data Binding in React"; text, checkbox, radio ve select ile bağlama.²

• Yazı: Adrian Roselli, "Avoid Default Field Validation"; tarayıcı doğrulamasının erişilebilirlik sorunları.⁶