Componenti controllati e non controllati in React

Un componente controllato è un elemento di form il cui valore vive nello stato React: passi value e aggiorni lo stato in onChange, quindi è React a decidere cosa mostra l'input. Un componente non controllato tiene il suo valore nel DOM, come l'HTML semplice: passi un defaultValue iniziale e leggi il valore attuale più tardi tramite un ref o FormData.

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>
    );
}

Scrivi in entrambi gli input. Il paragrafo segue il primo a ogni tasto, perché ogni modifica imposta lo stato e provoca un nuovo render. Il secondo input cambia solo nel DOM; React non esegue alcun rendering, e vedi il suo valore solo quando "Read both" lo chiede.

Input controllati

Con un input controllato, lo stato React è l'unica fonte di verità. Il flusso a ogni tasto è:

1. L'utente scrive, e il browser genera un evento input.
2. Il tuo gestore onChange legge e.target.value e chiama il setter.
3. React esegue un nuovo render e riscrive il nuovo stato nel value dell'input.

Poiché il tuo codice sta in mezzo a quel ciclo, puoi fare cose che un input non controllato non può: rifiutare o rimodellare caratteri, mostrare il valore da un'altra parte, disabilitare un pulsante finché il valore non è valido, o impostare il valore dal codice (un pulsante "Clear", un suggerimento che l'utente clicca).

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>
    );
}

Prova a scrivere lettere: non compaiono mai, perché il gestore toglie tutto ciò che non è una cifra prima di impostare lo stato. Il pulsante Verify resta disabilitato finché non ci sono esattamente sei cifre.

Controllato è ciò che usano gli esempi di form della pagina sui form, ed è la scelta predefinita nella maggior parte del codice React.

Input non controllati

Un input non controllato funziona come l'HTML semplice. React lo renderizza una volta con defaultValue (o defaultChecked per checkbox e radio) e poi lo lascia stare. Per leggere il valore, tieni un ref all'elemento oppure leggi tutti i campi con nome dal form all'invio con FormData.

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>
    );
}

Non c'è stato per i campi e non c'è onChange. I valori vengono raccolti solo quando il form viene inviato. Togli la spunta alla checkbox e invia di nuovo: la chiave subscribe sparisce, perché una checkbox non spuntata non fa proprio parte di FormData.

Cambiare defaultValue dopo il primo rendering non ha effetto sull'input, perché React lo applica solo quando l'elemento viene creato. Per azzerare un form non controllato, chiama e.target.reset(), oppure dai al form una nuova key così React crea input nuovi.

Un input in cui non puoi scrivere

Se passi value ma non onChange, l'input è controllato, ma nulla aggiorna mai lo stato. React riscrive lo stesso valore dopo ogni tasto, quindi l'input sembra bloccato.

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>
    );
}

Prova a scrivere in ogni campo. Il primo non cambia. Il secondo è la soluzione per un input controllato, e mentre scrivi lì, il primo e l'ultimo campo lo seguono, perché tutti e tre leggono lo stesso stato. Il terzo accetta la digitazione perché è non controllato. Il quarto dichiara di proposito che non può essere modificato.

In sviluppo, React registra un avviso per il primo input: "You provided a value prop to a form field without an onChange handler". L'anteprima gira come una build di produzione, quindi qui non vedrai quell'avviso, ma lo vedrai nel tuo server di sviluppo.

Passare da non controllato a controllato

React decide se un input è controllato guardando value. Se value è undefined o null, l'input è non controllato. Quindi un input il cui value parte come undefined e poi diventa una stringa passa da non controllato a controllato durante la sua vita, e React avvisa in sviluppo: "A component is changing an uncontrolled input to be controlled".

L'avviso indica un bug reale. Tornare indietro nell'altra direzione, da una stringa a undefined, rende di nuovo l'input non controllato, e React smette di scriverci.

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>
    );
}

Scrivi qualcosa in entrambi gli input e premi ciascun pulsante Clear. Il secondo input si svuota. Il primo mantiene il suo testo: impostare lo stato a undefined lo ha reso non controllato, quindi React non controlla più ciò che mostra.

La fonte abituale di undefined sono dati non ancora caricati (value={user.name} prima che arrivi l'utente) o un campo di un oggetto che non esiste ancora. Due soluzioni:

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

Per le checkbox la stessa regola vale per checked: fallo partire da false, non da undefined.

Gli input file sono sempre non controllati

Un <input type="file"> non può essere controllato, perché i browser non permettono a una pagina di impostarne il valore (una pagina che potesse scegliere file sul tuo disco sarebbe una falla di sicurezza). Leggi i file scelti da e.target.files in onChange, oppure tramite un ref quando il form viene inviato.

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>
    );
}

Scegli uno o due file dal tuo computer; non viene caricato nulla, l'esempio elenca solo nomi e dimensioni. L'unico valore che puoi impostare su un input file è la stringa vuota, ed è così che il pulsante Clear lo azzera.

Quando scegliere quale

Scegli controllato quando lo schermo deve reagire al valore mentre l'utente scrive. Scegli non controllato quando ti servono i valori solo alla fine, che è anche il modo in cui funzionano le form action di React 19: <form action={fn}> consegna alla tua funzione un FormData e poi azzera i campi non controllati.

Un rendering a ogni tasto sembra costoso, ma per un form normale non è un problema. Lo diventa solo quando un albero grande e lento esegue un nuovo render insieme all'input; in quel caso tieni lo stato vicino all'input, o sposta la parte lenta in un suo componente.

Le stesse due parole descrivono anche i tuoi componenti. Un componente che riceve il suo valore e un onChange dal genitore tramite props è controllato dal genitore; uno che tiene il proprio stato è non controllato. Spostare lo stato verso l'alto per rendere un componente controllato è l'argomento di sollevare lo stato.