Componentes controlados vs no controlados en React

Un componente controlado es un elemento de formulario cuyo valor vive en el estado de React: pasas value y actualizas el estado en onChange, así que React decide qué muestra el input. Un componente no controlado guarda su valor en el DOM, como en HTML puro: pasas un defaultValue inicial y lees el valor actual después mediante una 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>
    );
}

Escribe en ambos inputs. El párrafo sigue al primero en cada pulsación, porque cada cambio actualiza el estado y vuelve a renderizar. El segundo input cambia solo en el DOM; React no renderiza, y solo ves su valor cuando "Read both" lo pide.

Inputs controlados

Con un input controlado, el estado de React es la única fuente de verdad. El flujo en cada pulsación es:

1. El usuario escribe y el navegador dispara un evento de input.
2. Tu manejador onChange lee e.target.value y llama al setter.
3. React vuelve a renderizar y escribe el nuevo estado en el value del input.

Como tu código está en medio de ese ciclo, puedes hacer cosas que un input no controlado no puede: rechazar o transformar caracteres, mostrar el valor en otro lugar, deshabilitar un botón hasta que el valor sea válido, o definir el valor desde el código (un botón "Clear", una sugerencia en la que el usuario hace clic).

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

Prueba a escribir letras: nunca aparecen, porque el manejador quita todo lo que no sea un dígito antes de actualizar el estado. El botón Verify sigue deshabilitado hasta que haya exactamente seis dígitos.

Controlado es lo que usan los ejemplos de la página de formularios, y es la opción por defecto en la mayor parte del código de React.

Inputs no controlados

Un input no controlado funciona como en HTML puro. React lo renderiza una vez con defaultValue (o defaultChecked para casillas y radios) y luego lo deja en paz. Para leer el valor, guarda una ref al elemento o lee todos los campos con nombre del formulario al enviar 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>
    );
}

No hay estado para los campos ni onChange. Los valores se recogen solo cuando el formulario se envía. Desmarca la casilla y envía otra vez: la clave subscribe desaparece, porque una casilla sin marcar no forma parte de FormData en absoluto.

Cambiar defaultValue después del primer renderizado no le hace nada al input, porque React solo lo aplica cuando se crea el elemento. Para reiniciar un formulario no controlado, llama a e.target.reset(), o dale al formulario una key nueva para que React cree inputs nuevos.

Un input en el que no puedes escribir

Si pasas value pero no onChange, el input es controlado, pero nada actualiza nunca el estado. React vuelve a escribir el mismo valor después de cada pulsación, así que el input parece congelado.

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

Prueba a escribir en cada campo. El primero no cambia. El segundo es la solución para un input controlado, y mientras escribes ahí, el primer y el último campo lo siguen, porque los tres leen el mismo estado. El tercero acepta lo que escribes porque es no controlado. El cuarto dice a propósito que no se puede editar.

En desarrollo, React registra un aviso para el primer input: "You provided a value prop to a form field without an onChange handler". La vista previa funciona como un build de producción, así que aquí no verás ese aviso, pero sí en tu propio servidor de desarrollo.

Pasar de no controlado a controlado

React decide si un input es controlado mirando value. Si value es undefined o null, el input es no controlado. Así que un input cuyo value empieza como undefined y luego pasa a ser una cadena cambia de no controlado a controlado durante su vida, y React avisa en desarrollo: "A component is changing an uncontrolled input to be controlled".

El aviso señala un error real. Volver en la otra dirección, de una cadena a undefined, hace que el input vuelva a ser no controlado, y React deja de escribir en él.

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

Escribe algo en ambos inputs y pulsa cada botón Clear. El segundo input se vacía. El primero conserva su texto: poner el estado en undefined lo volvió no controlado, así que React ya no controla lo que muestra.

La fuente habitual de undefined son datos que aún no han cargado (value={user.name} antes de que llegue el usuario) o un campo de objeto que todavía no existe. Dos soluciones:

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

Para las casillas la misma regla se aplica a checked: empiézalo en false, no en undefined.

Los inputs de archivo siempre son no controlados

Un <input type="file"> no puede ser controlado, porque los navegadores no permiten que una página defina su valor (una página que pudiera elegir archivos de tu disco sería un agujero de seguridad). Lee los archivos elegidos desde e.target.files en onChange, o mediante una ref cuando se envía el formulario.

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

Elige uno o dos archivos de tu computadora; no se sube nada, el ejemplo solo lista nombres y tamaños. El único valor que puedes asignar a un input de archivo es la cadena vacía, que es como el botón Clear lo reinicia.

Cuándo elegir cuál

Elige controlado cuando la pantalla tiene que reaccionar al valor mientras el usuario escribe. Elige no controlado cuando solo necesitas los valores al final, que es también como funcionan las acciones de formulario de React 19: <form action={fn}> le entrega a tu función un FormData y después reinicia los campos no controlados.

Renderizar en cada pulsación suena costoso, pero en un formulario normal no es un problema. Solo lo es cuando un árbol grande y lento se vuelve a renderizar con el input; en ese caso, mantén el estado cerca del input o mueve la parte lenta a su propio componente.

Las mismas dos palabras describen también tus propios componentes. Un componente que recibe su valor y un onChange de su padre mediante props está controlado por el padre; uno que guarda su propio estado es no controlado. Mover el estado hacia arriba para hacer un componente controlado es de lo que trata elevar el estado.