Cenários de Bugs em Formulários & Inputs

Dez tickets de bugs do mundo real sobre comportamento de formulários, controles de input, validação e submissão. Cada entrada mostra o ticket não técnico, o diagnóstico, uma correção concisa e por que a correção está correta.

Como Usar Esta Lista

• Bugs de formulário se concentram em quatro causas: onChange ausente (controlado), assinatura de handler incorreta, tipo de input incorreto e valores padrão ausentes.
• Sempre verifique se o input é controlado, não controlado ou um híbrido - a maioria dos bugs de formulário se esconde nessa fronteira.

1. "Não consigo digitar no campo de e-mail no formulário de cadastro"

"Tentei me cadastrar. A caixa de e-mail não aceita nenhuma entrada - eu pressiono teclas e nada acontece. Outros campos funcionam."

Diagnóstico: O input tem uma prop value mas sem onChange, tornando-o um input controlado somente leitura.

Correção:

"use client";
import { useState } from "react";
 
export function EmailField() {
  const [email, setEmail] = useState("");
  return (
    <input
      type="email"
      value={email}
      onChange={(e) => setEmail(e.target.value)}
    />
  );
}

Por que isso funciona: React exige value e onChange para inputs controlados. O onChange é o que realmente muta o estado a cada pressionamento de tecla, o que então re-renderiza o input com o novo value.

2. "Clicar no botão Submit recarrega a página e perde todas as minhas respostas"

"Estava preenchendo a pesquisa, cliquei em Submit no final, a página inteira recarregou e minhas respostas sumiram."

Diagnóstico: Um <form> sem onSubmit recorre à submissão nativa do formulário, que navega o navegador para a action do formulário (ou URL atual).

Correção:

"use client";
import { FormEvent, useState } from "react";
 
export function Survey() {
  const [name, setName] = useState("");
  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    saveSurvey({ name });
  };
  return (
    <form onSubmit={onSubmit}>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <button type="submit">Submit</button>
    </form>
  );
}

Por que isso funciona: e.preventDefault() cancela o submit nativo, então o navegador não recarrega. O handler executa sua lógica de salvamento com o estado atual do formulário em vez de descartar os dados.

3. "Quando digito rápido no campo de busca, meu cursor pula para o final do texto"

"Edito um nome no meio, digito um caractere, e o cursor pula para o final. Está enlouquecendo a equipe."

Diagnóstico: O input está sendo desmontado e remontado a cada pressionamento de tecla - geralmente porque está definido dentro de um componente pai que re-renderiza, ou por causa de uma key que muda.

Correção:

"use client";
// Defina componentes estáveis FORA de pais que re-renderizam
function NameInput({ value, onChange }: { value: string; onChange: (v: string) => void }) {
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}
 
export function Page() {
  const [name, setName] = useState("");
  return <NameInput value={name} onChange={setName} />;
}

Por que isso funciona: Componentes definidos dentro de outro componente são recriados a cada renderização, então React os trata como novos tipos e desmonta/remonta o input - perdendo o estado de seleção. Definir o componente no escopo do módulo mantém a instância do input estável entre as renderizações.

4. "O formulário limpa quando submeto um e-mail inválido - todos os meus outros campos são apagados"

"Grande formulário de checkout. Se o e-mail for inválido, mostramos o erro, mas todos os outros campos esvaziam ao mesmo tempo."

Diagnóstico: O formulário usa defaultValue em inputs não controlados sem os padrões useForm, então re-renderiza com novas chaves ou remonta na validação, limpando o estado do DOM.

Correção:

"use client";
import { useForm } from "react-hook-form";
 
interface CheckoutForm {
  email: string;
  name: string;
  address: string;
}
 
export function Checkout() {
  const { register, handleSubmit, formState: { errors } } = useForm<CheckoutForm>({
    defaultValues: { email: "", name: "", address: "" },
  });
  return (
    <form onSubmit={handleSubmit((data) => save(data))}>
      <input {...register("email", { pattern: /^[^@]+@[^@]+$/ })} />
      {errors.email && <p>Email inválido</p>}
      <input {...register("name")} />
      <input {...register("address")} />
      <button type="submit">Pagar</button>
    </form>
  );
}

Por que isso funciona: React Hook Form gerencia o estado do campo em um store baseado em ref, então erros de validação disparam re-renderizações sem remontar inputs ou perder seus valores. Os valores dos campos sobrevivem a cada ciclo de validação.

5. "A caixa de seleção 'Lembrar-me' sempre envia como marcada mesmo quando eu desmarco"

"'Lembrar-me' do formulário de login está travado. O estado mostra como desmarcado visualmente, mas a API sempre recebe true."

Diagnóstico: A caixa de seleção está vinculada com value em vez de checked, então React renderiza o atributo value como uma string, mas nunca controla realmente o estado de marcado.

Correção:

"use client";
import { useState } from "react";
 
export function RememberMe() {
  const [remember, setRemember] = useState(false);
  return (
    <label>
      <input
        type="checkbox"
        checked={remember}
        onChange={(e) => setRemember(e.target.checked)}
      />
      Lembrar-me
    </label>
  );
}

Por que isso funciona: Caixas de seleção usam checked e e.target.checked - não value e e.target.value. O atributo value em uma caixa de seleção é a string literal enviada na submissão quando marcada, não se ela está selecionada.

6. "O campo 'idade' salva como texto em vez de número, e nosso filtro de idade quebra"

"Suporte ao cliente diz que o campo de idade aceita texto. Relatórios mostram idades como '42' entre aspas - filtros que esperam números falham."

Diagnóstico: <input type="number"> ainda retorna uma string de e.target.value. O valor deve ser convertido explicitamente.

Correção:

"use client";
import { useState } from "react";
 
export function AgeField() {
  const [age, setAge] = useState<number | null>(null);
  return (
    <input
      type="number"
      value={age ?? ""}
      onChange={(e) => {
        const v = e.target.valueAsNumber;
        setAge(Number.isNaN(v) ? null : v);
      }}
    />
  );
}

Por que isso funciona: valueAsNumber retorna um número ou NaN diretamente. Armazenar null quando o campo está vazio evita a coerção de strings vazias para 0 e corresponde a como uma API JSON espera um valor ausente.

7. "Aniversários aparecem com um dia de diferença no registro do cliente"

"Escolhemos um aniversário no seletor de data, salvamos, e a página de detalhes do cliente mostra o dia anterior. Reproduzível para todos."

Diagnóstico: new Date("1990-05-14") é analisado como meia-noite UTC, mas toLocaleDateString() renderiza em hora local - que é o dia anterior em qualquer fuso horário a oeste do UTC.

Correção:

export function formatBirthday(iso: string): string {
  const [y, m, d] = iso.split("-").map(Number);
  return new Date(y, m - 1, d).toLocaleDateString();
}

Por que isso funciona: Construir a Data com argumentos numéricos a cria em hora local, correspondendo à data que o usuário realmente escolheu. Strings ISO implicam UTC e silenciosamente mudam entre limites de fuso horário - o caso de data de calendário precisa de um parser de data de calendário.

8. "Pressionar Enter na barra de busca dispara a busca duas vezes"

"Barra de busca no topo - se eu pressionar Enter, a aba de rede mostra duas requisições com a mesma query."

Diagnóstico: Tanto onKeyDown (Enter) quanto o submit implícito do formulário são acionados, cada um disparando sua própria chamada de busca.

Correção:

"use client";
import { FormEvent, useState } from "react";
 
export function SearchBar() {
  const [q, setQ] = useState("");
  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    search(q);
  };
  return (
    <form onSubmit={onSubmit}>
      <input value={q} onChange={(e) => setQ(e.target.value)} />
      <button type="submit">Ir</button>
    </form>
  );
}

Por que isso funciona: Pressionar Enter dentro de um formulário já o submete - não há necessidade de escutar Enter separadamente. Remover o handler onKeyDown e confiar em onSubmit torna o único caminho de submit o único caminho.

9. "Campos desabilitados não são incluídos nos dados que salvamos"

"Desabilitamos certos campos quando eles são 'travados'. Ao salvar, esses campos estão faltando no corpo da requisição, mesmo que estejam visíveis."

Diagnóstico: FormData nativo pula inputs desabilitados por design - eles não são considerados parte da submissão do formulário.

Correção:

// Ou:
<input name="planId" value={planId} readOnly />
// Ou inclua o valor explicitamente ao construir o payload:
const payload = { ...Object.fromEntries(new FormData(form)), planId };

Por que isso funciona: readOnly mantém o campo não editável, mas ainda submetível, enquanto disabled o remove completamente do FormData. Se a UX precisar de disabled, o handler de submissão deve mesclar os valores ausentes manualmente.

10. "A barra de progresso de upload de arquivos nunca se move - pula de 0% para 100%"

"Clientes podem anexar arquivos, mas a barra de progresso está quebrada. Ela fica em 0%, depois pula para 100% quando o upload termina."

Diagnóstico: O upload usa fetch, que não expõe eventos de progresso do lado da requisição. Apenas XMLHttpRequest (ou uma abstração ciente de streaming) relata bytes de upload.

Correção:

"use client";
export function uploadWithProgress(file: File, onProgress: (pct: number) => void): Promise<void> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.upload.addEventListener("progress", (e) => {
      if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
    });
    xhr.addEventListener("load", () => (xhr.status < 400 ? resolve() : reject(new Error(xhr.statusText))));
    xhr.addEventListener("error", () => reject(new Error("Network error")));
    xhr.open("POST", "/api/upload");
    const fd = new FormData();
    fd.append("file", file);
    xhr.send(fd);
  });
}

Por que isso funciona: xhr.upload.progress é a única API do navegador que relata bytes enviados do lado da requisição. Os corpos de requisição ReadableStream do Fetch não expõem progresso de forma cross-browser hoje, então XHR ainda é a ferramenta certa para UIs de progresso de upload.

Relacionado

• Noções Básicas de Formulários & Validação - Padrões fundamentais de formulários.
• Receitas do React Hook Form - Padrões específicos da biblioteca.
• Eventos React - Tipagem e comportamento de handlers de eventos.