Componentes controlados vs não controlados no React

Um componente controlado é um elemento de formulário cujo valor mora no estado do React: você passa value e atualiza o estado no onChange, então é o React que decide o que o input mostra. Um componente não controlado guarda o valor no DOM, como no HTML puro: você passa um defaultValue inicial e lê o valor atual depois por uma ref ou com 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>
    );
}

Digite nos dois inputs. O parágrafo acompanha o primeiro a cada tecla, porque cada mudança define o estado e renderiza de novo. O segundo input muda só no DOM; o React não renderiza, e você só vê o valor dele quando "Read both" o pede.

Inputs controlados

Com um input controlado, o estado do React é a única fonte da verdade. O fluxo a cada tecla é:

1. O usuário digita, e o navegador dispara um evento de input.
2. O seu handler de onChange lê e.target.value e chama o setter.
3. O React renderiza de novo e escreve o novo estado de volta no value do input.

Como o seu código fica no meio desse ciclo, você pode fazer coisas que um input não controlado não consegue: rejeitar ou remodelar caracteres, mostrar o valor em outro lugar, desabilitar um botão até o valor ser válido ou definir o valor pelo código (um botão "Clear", uma sugestão que o usuário clica).

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

Tente digitar letras: elas nunca aparecem, porque o handler remove tudo o que não é dígito antes de definir o estado. O botão Verify fica desabilitado até haver exatamente seis dígitos.

Controlado é o que os exemplos de formulário da página de formulários usam, e é a escolha padrão na maior parte do código React.

Inputs não controlados

Um input não controlado funciona como HTML puro. O React o renderiza uma vez com defaultValue (ou defaultChecked para checkboxes e rádios) e depois o deixa em paz. Para ler o valor, guarde uma ref para o elemento ou leia todos os campos com nome do formulário no envio, com 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>
    );
}

Não há estado para os campos nem onChange. Os valores só são coletados quando o formulário é enviado. Desmarque o checkbox e envie de novo: a chave subscribe desaparece, porque um checkbox desmarcado simplesmente não faz parte do FormData.

Mudar o defaultValue depois da primeira renderização não faz nada no input, já que o React só o aplica quando o elemento é criado. Para reiniciar um formulário não controlado, chame e.target.reset() ou dê ao formulário uma nova key para que o React crie inputs novos.

Um input em que não dá para digitar

Se você passa value mas nenhum onChange, o input é controlado, mas nada nunca atualiza o estado. O React escreve o mesmo valor de volta depois de cada tecla, então o 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>
    );
}

Tente digitar em cada campo. O primeiro não muda. O segundo é a correção para um input controlado, e enquanto você digita nele, o primeiro e o último campos o acompanham, porque os três leem o mesmo estado. O terceiro aceita digitação porque é não controlado. O quarto diz de propósito que não pode ser editado.

Em desenvolvimento, o React registra um aviso para o primeiro input: "You provided a value prop to a form field without an onChange handler". A prévia roda como um build de produção, então você não vai ver esse aviso aqui, mas vai vê-lo no seu próprio servidor de desenvolvimento.

Mudando de não controlado para controlado

O React decide se um input é controlado olhando para value. Se value é undefined ou null, o input é não controlado. Então um input cujo value começa como undefined e depois vira uma string passa de não controlado para controlado ao longo da vida, e o React avisa em desenvolvimento: "A component is changing an uncontrolled input to be controlled".

O aviso aponta para um bug real. Voltar no sentido contrário, de uma string para undefined, torna o input não controlado de novo, e o React para de escrever nele.

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

Digite algo nos dois inputs e aperte cada botão Clear. O segundo input fica vazio. O primeiro mantém o texto: definir o estado como undefined o tornou não controlado, então o React não controla mais o que ele mostra.

A origem comum do undefined são dados que ainda não carregaram (value={user.name} antes de o usuário chegar) ou um campo de objeto que ainda não existe. Duas correções:

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

Para checkboxes, a mesma regra vale para checked: comece com false, não undefined.

Inputs de arquivo são sempre não controlados

Um <input type="file"> não pode ser controlado, porque os navegadores não deixam uma página definir o valor dele (uma página que pudesse escolher arquivos do seu disco seria uma falha de segurança). Leia os arquivos escolhidos em e.target.files no onChange, ou por uma ref quando o formulário for enviado.

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

Escolha um ou dois arquivos do seu computador; nada é enviado, o exemplo só lista nomes e tamanhos. O único valor que você pode definir em um input de arquivo é a string vazia, e é assim que o botão Clear o reinicia.

Quando escolher cada um

Escolha controlado quando a tela precisa reagir ao valor enquanto o usuário digita. Escolha não controlado quando você só precisa dos valores no final, que também é como funcionam as form actions do React 19: <form action={fn}> entrega à sua função um FormData e reinicia os campos não controlados depois.

Renderizar a cada tecla parece caro, mas para um formulário normal não é problema. Só vira problema quando uma árvore grande e lenta renderiza de novo junto com o input; aí mantenha o estado perto do input ou mova a parte lenta para um componente próprio.

As mesmas duas palavras descrevem os seus próprios componentes. Um componente que recebe o valor e um onChange do pai pelas props é controlado pelo pai; um que guarda o próprio estado é não controlado. Mover o estado para cima para tornar um componente controlado é o assunto de elevar o estado.