Tarayıcıya yerleşik <input> bileşeni farklı türden form girdileri render etmenizi sağlar.

<input />

Referans

<input>

Ekranda bir girdi göstermek için, tarayıcıya yerleşik <input> bileşenini render edin.

<input name="myInput" />

Daha fazla örnek için aşağıya bakınız.

Prop’lar

<input> tüm ortak eleman proplarını destekler.

Test Ortamı (Canary)

React’s extensions to the formAction prop are currently only available in React’s Canary and experimental channels. In stable releases of React, formAction works only as a built-in browser HTML component. Learn more about React’s release channels here.

formAction: String ya da fonksiyon. Tipi type="submit" ve type="image" olan girdiler için <form action> üst bileşenini geçersiz kılar. action’a bir URL geçildiği zaman form, standart bir HTML formu gibi davranacaktır. Bir fonksiyon iletildiğinde ise form gönderimini o fonksiyon halledecektir. Daha fazla bilgi için <form action> kısmına bakın.

Aşağıdaki proplardan birini ileterek girdileri kontrollü hale getirebilirsiniz:

  • checked: Boolean. Onay kutusu girdisi ya da radyo butonunun seçilip seçilmediğini kontrol eder.
  • value: String. Metin kutusunun içindeki metni kontrol eder. (Radyo butonu için, form verisini belirtir.)

İki propdan birini ilettiğinizde, iletilen değeri güncelleyen onChange olay yöneticisini de iletmeniz gerekmektedir.

Aşağıdaki <input> propları sadece kontrolsüz girdilerle ilgilidir:

Aşağıdaki <input> proplar hem kontrollü hem de kontrolsüz girdilerle ilgilidir:

  • accept: String. Tipi type="file" olan girdiler için hangi dosya tiplerinin kabul edilebilir olduğunu belirler.
  • alt: String. Tipi type="image" olan girdiler için alternatif görüntü metnini belirler.
  • capture: String. Tipi type="file" olan girdiler için yakalanan medyayı (mikrofon, video ya da kamera) belirler.
  • autoComplete: String. Olası otomatik tamamlama davranışları’ndan birini belirler.
  • autoFocus: Boolean. Eğer true ise, React, eleman DOM’a eklendikten sonra o elemana odaklanacaktır.
  • dirname: String. Bileşen yönlendirmesi için form alanı adını belirler.
  • disabled: Boolean. Eğer true ise, girdi etkileşimli olmayacak ve soluk renkli görünecektir.
  • children: <input> alt bileşen kabul etmez.
  • form: String. Girdinin ait olduğu <form>’un <id>’sini belirtir. Eğer belirtilmemişse, ağaçtaki en yakın üst formdur.
  • formAction: String. Tipi type="submit" ve type="image" olan girdiler için <form action> üst bileşenini geçersiz kılar.
  • formEnctype: String. Tipi type="submit" ve type="image" olan girdiler için <form enctype> üst bileşenini geçersiz kılar.
  • formMethod: String. Tipi type="submit" ve type="image" olan girdiler için <form method> üst bileşenini geçersiz kılar.
  • formNoValidate: String. Tipi type="submit" ve type="image" olan girdiler için <form- noValidate> üst bileşenini geçersiz kılar.
  • formTarget: String. Tipi type="submit" and type="image" olan girdiler için <form target> üst bileşenini geçersiz kılar.
  • height: String. Tipi type="image" olan girdiler için görsel yükseliğini belirler.
  • list: String. Otomatik tamamlama seçeneği olan <datalist> bileşeninin id’sini belirler.
  • max: Numara. Tarih ve nümerik girdilerin maksimumum alabilecekleri değeri belirler.
  • maxLength: Numara. Metin ve diğer girdi tipleri için maksimum uzunluğu belirler.
  • min: Numara. Nümerik ve tarih girdilerin minimum alabilecekleri değeri belirler.
  • minLength: Numara. Metin ve diğer girdi tipleri için minimum uzunluğu belirler.
  • multiple: Boolean. Tipi <type="file" ve type="email" olan girdilerin çoklu değere sahip olup olamayacağını belirler.
  • name: String. Form ile birlikte gönderilen girdinin adını belirler.
  • onChange: Olay yöneticisi fonksiyonu. Kontrollü girdiler için gereklidir. Kullanıcı tarafından girdi değeri değiştiği anda (örneğin, klavyede her tuşa basıldığında) çalışır. [Tarayıcı input olayı] (https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) gibi çalışır.
  • onChangeCapture: [Yakalama aşamasında] (/learn/responding-to-events#capture-phase-events) çalışan onChange’in bir versiyonudur.
  • onInput: Olay yöneticisi fonksiyonu. Değer, kullanıcı tarafından değiştirildiği anda çalıştırılır. Tarihsel nedenlerden dolayı, React’te benzer şekilde çalışan onChange’i kullanmak yaygındır.
  • onInputCapture: onInput’un yakalama aşamasında çalıştırılan versiyonudur.
  • onInvalid: Olay yöneticisi fonksiyonu. Bir girdi, form gönderiminde doğrulamayı geçemezse çalıştırılır. Yerleşik invalid olayının aksine, React onInvalid olayı kabarcık şeklinde yayılır (bubbles).
  • onInvalidCapture: onInvalid’in yakalama aşamasında çalıştırılan bir versiyionudur.
  • onSelect: Olay yöneticisi fonksiyonu. <input> içindeki seçilen alanın değişmesiyle tetiklenir. React, onSelect olayını boş seçim ve düzenlemelerde de (seçimi etkileyebilir) çalıştırır.
  • onSelectCapture: onSelect’in yakalama aşamasında çalıştırılan bir versiyonudur.
  • pattern: String. value değerinin eşleşmesi gereken şablonu belirler.
  • placeholder: String. Girdi değeri yokken ekranda soluk renkte görüntülenir.
  • readOnly: Boolean. Eğer true ise, girdi alanı kullanıcı tarafından düzenlenemez.
  • required: Boolean. Eğer true ise, formun gönderilebilmesi için değer sağlanmalıdır.
  • size: Numara. Genişlik ayarına benzerdir ancak birimin türü kontrole bağlıdır.
  • src: String. Tipi type="image" olan girdiler için görsel kaynağını belirler.
  • step: Pozitif sayı ya da 'any' string. Geçerli iki değer araasındaki uzaklığı belirler.
  • type: String. Girdi tipleri’nden biridir.
  • width: String. Tipi type="image" olan girdiler için görsel genişliğini belirler.

Uyarılar

  • Onay kutularının value (veyadefaultValue) yerinechecked (veya defaultChecked) değerine ihtiyacı vardır.
  • Metin girdisi value propuna string değer alırsa kontrollü bileşen olarak ele alınır.
  • Onay kutusu ya da radyo butonu checked propuna boolean değer alırsa kontrollü bileşen olarak ele alınır.
  • Bir girdi aynı anda hem kontrollü hem de kontrolsüz olamaz.
  • Bir girdi yaşam döngüsü boyunca kontrollü ve kontrolsüz olma arasında geçiş yapamaz.
  • Kontrollü tüm girdiler, değeri senkronize olarak güncelleyen onChange olay yöneticisine ihtiyaç duyar.

Kullanım

Farklı tiplerde girdileri gösterme

Ekranda <input>’u görülemek için render ediniz. Varsayılan olarak metin girdisi olacaktır. Onay kutusu için type="checkbox", radyo butonu için type="radio" veya diğer girdi tiplerinden birini gönderebilirsiniz.

export default function MyForm() {
  return (
    <>
      <label>
        Text input: <input name="myInput" />
      </label>
      <hr />
      <label>
        Checkbox: <input type="checkbox" name="myCheckbox" />
      </label>
      <hr />
      <p>
        Radio buttons:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Option 1
        </label>
        <label>
          <input type="radio" name="myRadio" value="option2" />
          Option 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Option 3
        </label>
      </p>
    </>
  );
}

Girdi için etiket verme

Genel olarak her <input> elemanını bir, <label> elemanı içine yerleştirirsiniz. Bu, tarayıcıya bu etkietin o metin alanıyla ilişkili olduğunu söyler. Kullanıcı bu etikete tıkladığında, tarayıcı o metin alanına odaklanır. Bu durum ayrıca erişebilirlik için de önemlidir: kullanıcı metin alanına tıkladığında ekran okuyucu bu etiketi okuyacaktır.

Eğer <input> elemanını bir <label> elemanının içine yerleştiremezseniz, <input id> ve <label htmlFor>. elemanlarına aynı ID’yi ileterek bu elemanları ilişkilendirebilirsiniz. Bir bileşenein birden fazla örnekleri arasındaki çakışmaları önlemek için useId ile ID üretebilirsiniz.

import { useId } from 'react';

export default function Form() {
  const ageInputId = useId();
  return (
    <>
      <label>
        Adınız:
        <input name="ad" />
      </label>
      <hr />
      <label htmlFor={ageInputId}>Yaşınız:</label>
      <input id={ageInputId} name="yas" type="number" />
    </>
  );
}

Girdiye başlangıç değeri verme

Her girdi tipi için başlangıç değeri verebilirsiniz. Metin girdileri için string tipinde defaultValue değeri iletebilirsiniz. Onay kutusu ve radyo butonları için başlangıç değerlerini boolean tipinde defaultChecked değeriyle belirleyebilirsiniz.

export default function MyForm() {
  return (
    <>
      <label>
        Metin girdisi: <input name="myInput" defaultValue="Some initial value" />
      </label>
      <hr />
      <label>
        Onay kutusu: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
      </label>
      <hr />
      <p>
        Radyo butonları:
        <label>
          <input type="radio" name="myRadio" value="option1" />
          Seçenek 1
        </label>
        <label>
          <input
            type="radio"
            name="myRadio"
            value="option2"
            defaultChecked={true} 
          />
          Seçenek 2
        </label>
        <label>
          <input type="radio" name="myRadio" value="option3" />
          Seçenek 3
        </label>
      </p>
    </>
  );
}

Formu gönderirken girdi değerlerini okuma

<button type="submit"> ve girdilerinizi çevreleyen bir <form> ekleyin. Eklediğiniz buton <form onSubmit> olay yöneticisini çağıracaktır. Varsayılan olarak, tarayıcı form verilerini bulunduğunuz URL’e gönderecek ve sayfayı yenileyecektir. e.preventDefault() ifadesini çağırarak bu işlemi engelleyebilirsiniz. Form verilerini new FormData(e.target) ile okuyabilirsiniz.

export default function MyForm() {
  function handleSubmit(e) {
    // Tarayıcının sayfayı yenilemesini engelleyin
    e.preventDefault();

    // Form verisini okuyun
    const form = e.target;
    const formData = new FormData(form);

    // formDatayı fetch gövdesi olarak iletebilirsiniz:
    fetch('/some-api', { method: form.method, body: formData });

    // formDatayı Düz nesne gibi de kullanabilirsiniz 
    const formJson = Object.fromEntries(formData.entries());
    console.log(formJson);
  }

  return (
    <form method="post" onSubmit={handleSubmit}>
      <label>
        Metin girdisi: <input name="myInput" defaultValue="Some initial value" />
      </label>
      <hr />
      <label>
        Onay kutusu: <input type="checkbox" name="myCheckbox" defaultChecked={true} />
      </label>
      <hr />
      <p>
        Radyo butonları:
        <label><input type="radio" name="myRadio" value="option1" /> Seçenek 1</label>
        <label><input type="radio" name="myRadio" value="option2" defaultChecked={true} /> Seçenek 2</label>
        <label><input type="radio" name="myRadio" value="option3" /> Seçenek 3</label>
      </p>
      <hr />
      <button type="reset">Formu sıfırla</button>
      <button type="submit">Forumu gönder</button>
    </form>
  );
}

Not

Tüm <input> elemanlarınıza bir name değeri verin, örneğin <input name="firstName" defaultValue="Taylor">. Bu name değeri form verilerinde anahtar olarak kullanılacaktır, örneğin { firstName: "Taylor" }.

Tuzak

Varsayılan olarak <form> içindeki herhangi bir <button> elemanı forumu gönderecektir. Bu biraz şaşırtıcı olabilir, kendinize ait React Button elemanınız varsa, <button> yerine <button type="button"> döndürmeyi düşünebilirsiniz. Daha açık olmak gerekise formu göndermesi gereken butonlar için <button type="submit"> kullanınız.

Durum değişkeniyle girdiyi kontrol etme

<input /> şeklindeki girdiler kontrolsüzdür. <input defaultValue="Başlangıç değeri" /> gibi başlangıç değeri iletseniz bile, JSX’iniz şu anki değeri değil, yalnızca başlangıç değerini belirtir.

_kontrollü girdi render etmek için, value propunu iletin (veya onay kutuları ve radyo butonları için checked). React, her zaman girdi değerinin sizin ilettiğiniz value değeri olması için zorlayacaktır. Genelde, durum değişkeni: tanımlayarak girdinizi kontrol edersiniz.

function Form() {
  const [firstName, setFirstName] = useState(''); // Durum değişkeni tanımlayınız...
  // ...
  return (
    <input
      value={firstName} //.. girdinin değerinin durum değişkeniyle eşleşmesi için zorlayınız...
      onChange={e => setFirstName(e.target.value)} //...ve her düzenlemede durum değişkenini güncelleyiniz!
    />
  );
}

Kontrollü bir girdi zaten duruma ihtiyacınız varsa kullanışlıdır, örneğin her düzenlemede arayüzü yeniden render etmek için:

function Form() {
  const [firstName, setFirstName] = useState('');
  return (
    <>
      <label>
        Ad:
        <input value={firstName} onChange={e => setFirstName(e.target.value)} />
      </label>
      {firstName !== '' && <p>Adınız {firstName}.</p>}
      ...

Ayrıca birden çok girdi seçeneği vermek isterseniz de kullanışlıdır (butona tıklamak gibi) :

function Form() {
  // ...
  const [age, setAge] = useState('');
  const ageAsNumber = Number(age);
  return (
    <>
      <label>
        Yaş:
        <input
          value={age}
          onChange={e => setAge(e.target.value)}
          type="number"
        />
        <button onClick={() => setAge(ageAsNumber + 10)}>
          10 yıl ekle
        </button>

Kontrollü bileşenlere ilettiğiniz value değeri undefined veya null olmamalıdır. Başlangıç değerinin boş olması gerekiyorsa (örneğin aşağıdaki firstName alanı), durum değişkeninizi boş string ('') olarak tanımyabilirsiniz.

import { useState } from 'react';

export default function Form() {
  const [firstName, setFirstName] = useState('');
  const [age, setAge] = useState('20');
  const ageAsNumber = Number(age);
  return (
    <>
      <label>
        Ad:
        <input
          value={firstName}
          onChange={e => setFirstName(e.target.value)}
        />
      </label>
      <label>
        Yaş:
        <input
          value={age}
          onChange={e => setAge(e.target.value)}
          type="number"
        />
        <button onClick={() => setAge(ageAsNumber + 10)}>
          10 yıl ekle
        </button>
      </label>
      {firstName !== '' &&
        <p>Adınız {firstName}.</p>
      }
      {ageAsNumber > 0 &&
        <p>Yaşınız {ageAsNumber}.</p>
      }
    </>
  );
}

Tuzak

Eğer onChange olay yöneticisi olmadan value değeri iletirseniz, girdiyi kullanmak imkansız olacaktır Girdiyi value değeri ileterek kontrol ettiğinizde, girdiyi sürekli olarak o değeri kullanmaya zorlarsınız. Bu nedenle durum değişkeni olarak value değeri ilettiğiniz sırada onChange olay yöneticisiyle de senkron olarak bu durum değişkenini güncellemeyi unutursanız, React klavyeye her basıldığında değişiklikleri ageri alıp belirttiğiniz value değerine dönecektir.

Her tuş vuruşunda yeniden render işlemininin iyileştirilmesi

Kontrollü girdi kullandığınızda, her klavye tıklamasında durumu ayarlarsınız. Durumun bulunduğu bileşeniniz her seferinde büyük bir ağacı yeniden render ederse bu işlem yavaş olabilir. Yeniden render performansınızı en iyi hale getirmek için birkaç yol bulunmaktadır.

Örneğin, her klavye girdisinde tüm sayfayı yeniden render eden bir form ile başlayalım:

function App() {
  const [firstName, setFirstName] = useState('');
  return (
    <>
      <form>
        <input value={firstName} onChange={e => setFirstName(e.target.value)} />
      </form>
      <PageContent />
    </>
  );
}

<PageContent /> girdi durumuna bağlı kalmadığı için girdi durumunu kendi bileşenine taşıyabilirsiniz:

function App() {
  return (
    <>
      <SignupForm />
      <PageContent />
    </>
  );
}

function SignupForm() {
  const [firstName, setFirstName] = useState('');
  return (
    <form>
      <input value={firstName} onChange={e => setFirstName(e.target.value)} />
    </form>
  );
}

Artık sadece SignupForm yeniden render edildiği için performans belirgin bir şekilde iyileşecektir.

Eğer yeniden renderı geçersiz kılacak bir yol yoksa (örneğin, PageContent arama girdisindeki değere bağlıysa), useDeferredValue kontrollü girdinizi büyük bir yeniden render sırasında bile duyarlı tutar.

Sorun giderme

Metin girdime yazarken güncellenmiyor

Girdinizi value değeri ile render ederken onChange olay yöneticisi yoksa, konsolda şu hatayı göreceksiniz:

// 🔴 Hata: kontrollü metin girdisinin onChange olay yöneticisi yok
<input value={something} />
Console
onChange yöneticisi olmayaan bir form alanına value propunu verdiniz. Bu salt okunur bir alan oluşturacaktır. Alanın değişken olması gerekiyorsa defaultValue kullanın. Aksi takdirde onChange veya readOnly olarak ayarlayın.

Hata mesajının önerdiği gibi, sadece başlangıç değeri belirlemek istiyorsanız defaultValue kullanın:

// ✅ İyi: başlangıç değeri olan kontrollü girdi
<input defaultValue={something} />

Girdi alanını durum değişkeni ile kontrol etmek için onChange yöneticisi belirleyin:

// ✅ İyi: onChange yöneticisi olan kontrollü girdi
<input value={something} onChange={e => setSomething(e.target.value)} />

Değer bilerek salt okunur ayarlanmak isteniyorsa, hatayı readOnly propu ekleyerek önleyebilirsiniz:

// ✅ İyi: salt okunur onChange olay yöneticisi olmayan kontrollü girdi
<input value={something} readOnly={true} />

Onay kutularım onlara tıkladığımda güncellenmiyor

Onay kutunuzu onChange olay yöneticisi olmadan checked değeri ile render ederseniz, konsolda şu hatayı göreceksiniz:

// 🔴 Hata: onChange yöneticisi olmayan kontrollü onay kutusu
<input type="checkbox" checked={something} />
Console
onChange yöneticisi olmayan bir form alanına checked propu verdiniz. Bu, salt okunur bir alan oluşturacaktır. Alanın değişken olması gerekiyorsa defaultChecked kullanın. Aksi takdirde onChange veya readOnly olarak ayarlayın.

Hata mesajında önerildiği üzere, başlangıç değeri belirlemek istiyorsanız defaultValue kullanın:

// ✅ İyi: başlangıç değeri olan kontrolsüz girdi
<input type="checkbox" defaultChecked={something} />

Onay kutusunu durum değişkeni ile kontrol etmek için onChange yöneticisi belirleyin:

// ✅ İyi: onChange yöneticisi olan kontrollü onay kutusu
<input type="checkbox" checked={something} onChange={e => setSomething(e.target.checked)} />

Tuzak

Onay kutularında e.target.value yerine e.target.checked değerini okumalısınız.

Onay kutusu bilerek salt okunur ayarlanmak isteniyorsa hatayı, readOnly propu ekleyerek önleyebilirsiniz:

// ✅ İyi: salt okunur onChange yöneticisi olan kontrollü girdi
<input type="checkbox" checked={something} readOnly={true} />

Girdideki imlecim klavyeden her girişte en başa atlıyor

Bir girdiyi kontrol ediyorsanız onChange sırasında DOM’daki durum değişkeni değerini girdi değerine güncellemelisiniz.

e.target.value (veya onay kutuları için e.target.checked) dışındaki başka bir değerle güncelleyemezsiniz:

function handleChange(e) {
  // 🔴 Hata: girdi değerini e.target.value dışında bir şeyle güncelleme
  setFirstName(e.target.value.toUpperCase());
}

Ayrıca asenkron olarak da güncelleyemezsiniz:

function handleChange(e) {
  // 🔴 Hata: girdiyi asenkron olarak güncelleme
  setTimeout(() => {
    setFirstName(e.target.value);
  }, 100);
}

Kodunuzu düzeltmek için, senkron bir şekilde e.target.value değeriyle güncelleyiniz:

function handleChange(e) {
  // ✅ Kontrollü girdiyi e.target.value değeriyle senkron güncelleme
  setFirstName(e.target.value);
}

Eğerbunlar sorununuzu çözmezse, girdiniz her klavye girişinde DOM’dan silinip geri ekleniyor olabilir. Bu durum, her yeniden renderda durumu sıfırlama’dan kaynaklı olabilir. Örneğin, eğer girdiniz ya da onun üstündeki elemanlardan biri süreki farklı key niteliği alıyor olabilir veya bileşen tanımlarını iç içe yerleştirmenizden kaynaklı olabilir (iç içe yerleştirmeler desteklenmemektedir ve “iç” bileşenin her zaman farklı bir ağaç olarak kabul edilmesine neden olur).

”Bir bileşen kontrolsüz girişi kontrol ediyor” hatası alıyorum

Bileşeninize value değeri verdiyseniz, yaşam döngüsü boyunca string olarak kalmalıdır.

Önce value={undefined} olarak değer iletip daha sonra value="some string" şeklinde değer iletemezsiniz çünkü React, kontrollü bileşen mi kontrolsüz bileşen mi bunu bilemez. Kontrollü bileşen her zaman value değer olarak string almalıdır, null ya da undefined almamalıdır.

value değeriniz API’den veya durum değişkeninden geliyorsa, başta null veya undefined olarak tanımlanmış olabilir. Bu durumda boş bir string ('') olarak tanımlayabilirsiniz veya value={someValue ?? ''} olarak iletip value değerinin string olup olmadığına emin olabilirsiniz.

Previous<form>
Next<option>