React'te Kontrollü ve Kontrolsüz Bileşenler

Kontrollü (controlled) bir bileşen, değeri React state'inde yaşayan bir form öğesidir: value aktarır ve state'i onChange içinde güncellersin, böylece input'un ne göstereceğine React karar verir. Kontrolsüz (uncontrolled) bir bileşen ise değerini düz HTML gibi DOM'da tutar: bir başlangıç defaultValue'su aktarır ve mevcut değeri sonra bir ref ya da FormData aracılığıyla okursun.

import { useRef, useState } from 'react';

export default function App() {
    const [controlled, setControlled] = useState('Ada');
    const uncontrolledRef = useRef(null);

    function readBoth() {
        console.log('controlled:', controlled);
        console.log('uncontrolled:', uncontrolledRef.current.value);
    }

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input
                value={controlled}
                onChange={(e) => setControlled(e.target.value)}
            />
            <input defaultValue="Linus" ref={uncontrolledRef} />
            <p>Controlled value in state: {controlled}</p>
            <button onClick={readBoth}>Read both</button>
        </div>
    );
}

İki input'a da yaz. Paragraf her tuş vuruşunda ilkini takip eder, çünkü her değişiklik state ayarlar ve yeniden render eder. İkinci input yalnızca DOM'da değişir; React render etmez ve değerini yalnızca "Read both" onu istediğinde görürsün.

Kontrollü input'lar

Kontrollü bir input'ta tek doğruluk kaynağı React state'idir. Her tuş vuruşundaki akış şöyledir:

1. Kullanıcı yazar ve tarayıcı bir input olayı tetikler.
2. onChange işleyicin e.target.value'yu okur ve setter'ı çağırır.
3. React yeniden render eder ve yeni state'i input'un value'suna geri yazar.

Kodun bu döngünün ortasında durduğu için kontrolsüz bir input'un yapamayacağı şeyleri yapabilirsin: karakterleri reddetmek ya da yeniden şekillendirmek, değeri başka bir yerde göstermek, değer geçerli olana kadar bir düğmeyi devre dışı bırakmak ya da değeri koddan ayarlamak (bir "Clear" düğmesi, kullanıcının tıkladığı bir öneri).

import { useState } from 'react';

export default function App() {
    const [code, setCode] = useState('');

    function handleChange(e) {
        const digits = e.target.value.replace(/\D/g, '').slice(0, 6);
        setCode(digits);
    }

    return (
        <div>
            <input
                value={code}
                onChange={handleChange}
                placeholder="6 digit code"
                style={{ letterSpacing: 6, fontSize: 18, width: 150 }}
            />{' '}
            <button disabled={code.length !== 6}>Verify</button>{' '}
            <button onClick={() => setCode('123456')}>Fill demo code</button>
        </div>
    );
}

Harf yazmayı dene: hiç görünmezler, çünkü işleyici state'i ayarlamadan önce rakam olmayan her şeyi ayıklar. Verify düğmesi tam olarak altı rakam olana kadar devre dışı kalır.

Formlar sayfasındaki form örnekleri kontrollü input kullanır ve çoğu React kodunda varsayılan seçim budur.

Kontrolsüz input'lar

Kontrolsüz bir input düz HTML gibi çalışır. React onu bir kez defaultValue (onay kutuları ve radyolar için defaultChecked) ile render eder ve sonra kendi hâline bırakır. Değeri okumak için ya öğeye bir ref tut ya da gönderimde formdaki tüm adlandırılmış alanları FormData ile oku.

import { useState } from 'react';

export default function App() {
    const [result, setResult] = useState(null);

    function handleSubmit(e) {
        e.preventDefault();
        const data = new FormData(e.target);
        setResult(Object.fromEntries(data));
    }

    return (
        <form onSubmit={handleSubmit}>
            <input name="city" defaultValue="Oslo" />{' '}
            <label>
                <input name="subscribe" type="checkbox" defaultChecked />
                Subscribe
            </label>{' '}
            <button type="submit">Send</button>
            {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
        </form>
    );
}

Alanlar için state ve onChange yoktur. Değerler yalnızca form gönderildiğinde toplanır. Onay kutusunun işaretini kaldır ve yeniden gönder: subscribe anahtarı kaybolur, çünkü işaretlenmemiş bir onay kutusu FormData'nın hiç parçası değildir.

İlk render'dan sonra defaultValue'yu değiştirmek input'a hiçbir şey yapmaz, çünkü React onu yalnızca öğe oluşturulurken uygular. Kontrolsüz bir formu sıfırlamak için e.target.reset() çağır ya da React'in taze input'lar oluşturması için forma yeni bir key ver.

Yazılamayan bir input

value aktarıp onChange aktarmazsan input kontrollüdür, ama hiçbir şey state'i asla güncellemez. React her tuş vuruşundan sonra aynı değeri geri yazar, bu yüzden input donmuş görünür.

import { useState } from 'react';

export default function App() {
    const [name, setName] = useState('Ada');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 260 }}>
            <input value={name} />
            <input value={name} onChange={(e) => setName(e.target.value)} />
            <input defaultValue={name} />
            <input value={name} readOnly />
        </div>
    );
}

Her alana yazmayı dene. İlki değişmez. İkincisi kontrollü bir input için çözümdür ve oraya yazdıkça ilk ve son alanlar onu takip eder, çünkü üçü de aynı state'i okur. Üçüncüsü kontrolsüz olduğu için yazmayı kabul eder. Dördüncüsü düzenlenemeyeceğini bilerek söyler.

Geliştirmede React ilk input için bir uyarı kaydeder: "You provided a value prop to a form field without an onChange handler". Önizleme bir production derlemesi gibi çalışır, bu yüzden bu uyarıyı burada görmezsin, ama kendi geliştirme sunucunda görürsün.

Kontrolsüzden kontrollüye geçmek

React bir input'un kontrollü olup olmadığına value'ya bakarak karar verir. value undefined ya da null ise input kontrolsüzdür. Yani value'su undefined olarak başlayıp sonra bir metne dönüşen bir input, ömrü boyunca kontrolsüzden kontrollüye geçer ve React geliştirmede uyarır: "A component is changing an uncontrolled input to be controlled".

Uyarı gerçek bir hataya işaret eder. Ters yöne, bir metinden undefined'a gitmek input'u yeniden kontrolsüz yapar ve React ona yazmayı bırakır.

import { useState } from 'react';

export default function App() {
    const [buggy, setBuggy] = useState(undefined);
    const [fixed, setFixed] = useState('');

    return (
        <div style={{ display: 'grid', gap: 8, maxWidth: 300 }}>
            <input
                value={buggy}
                onChange={(e) => setBuggy(e.target.value)}
                placeholder="Starts as undefined"
            />
            <button onClick={() => setBuggy(undefined)}>Clear first</button>
            <input
                value={fixed}
                onChange={(e) => setFixed(e.target.value)}
                placeholder="Starts as an empty string"
            />
            <button onClick={() => setFixed('')}>Clear second</button>
        </div>
    );
}

İki input'a da bir şey yaz ve her Clear düğmesine bas. İkinci input boşalır. İlki metnini korur: state'i undefined yapmak onu kontrolsüz yaptı, bu yüzden React artık ne gösterdiğini kontrol etmiyor.

undefined'ın olağan kaynağı henüz yüklenmemiş veri (kullanıcı gelmeden önce value={user.name}) ya da henüz var olmayan bir nesne alanıdır. İki çözüm:

const [name, setName] = useState('');   // start with a string
<input value={user?.name ?? ''} />       // or fall back to one

Onay kutuları için aynı kural checked'e uygulanır: onu undefined değil false ile başlat.

Dosya input'ları her zaman kontrolsüzdür

Bir <input type="file"> kontrol edilemez, çünkü tarayıcılar bir sayfanın değerini ayarlamasına izin vermez (diskindeki dosyaları seçebilen bir sayfa bir güvenlik açığı olurdu). Seçilen dosyaları onChange içinde e.target.files'tan ya da form gönderildiğinde bir ref aracılığıyla oku.

import { useRef, useState } from 'react';

export default function App() {
    const inputRef = useRef(null);
    const [files, setFiles] = useState([]);

    function handleChange(e) {
        setFiles(Array.from(e.target.files, (f) => `${f.name} (${f.size} bytes)`));
    }

    function clear() {
        inputRef.current.value = '';
        setFiles([]);
    }

    return (
        <div>
            <input type="file" multiple ref={inputRef} onChange={handleChange} />
            <button onClick={clear}>Clear</button>
            <ul>
                {files.map((f) => (
                    <li key={f}>{f}</li>
                ))}
            </ul>
            {files.length === 0 && <p>No files chosen.</p>}
        </div>
    );
}

Bilgisayarından bir iki dosya seç; hiçbir şey yüklenmez, örnek yalnızca adları ve boyutları listeler. Bir dosya input'una ayarlayabileceğin tek değer boş metindir; Clear düğmesi onu böyle sıfırlar.

Hangisi ne zaman seçilmeli

Ekranın kullanıcı yazarken değere tepki vermesi gerekiyorsa kontrollüyü seç. Değerlere yalnızca sonda ihtiyacın varsa kontrolsüzü seç; React 19 form action'ları da böyle çalışır: <form action={fn}> fonksiyonuna bir FormData verir ve sonrasında kontrolsüz alanları sıfırlar.

Her tuş vuruşunda render etmek pahalı gibi gelir, ama normal bir form için sorun değildir. Ancak büyük, yavaş bir ağaç input'la birlikte yeniden render olduğunda sorun hâline gelir; o zaman state'i input'a yakın tut ya da yavaş kısmı kendi bileşenine taşı.

Aynı iki kelime kendi bileşenlerini de tarif eder. Değerini ve bir onChange'i ebeveyninden props aracılığıyla alan bir bileşen ebeveyn tarafından kontrol edilir; kendi state'ini tutan bir bileşen ise kontrolsüzdür. Bir bileşeni kontrollü yapmak için state'i yukarı taşımak, state'i yukarı taşımak sayfasının konusudur.