Checkbox HTML: múltiplos valores, required e indeterminate

HTML <input type="checkbox"> permite que cada opção seja selecionada ou desmarcada independentemente. Apenas caixas marcadas enviam seu nome e valor; uma opção desmarcada é omitida dos dados enviados em vez de ser enviada como falso ou uma string vazia.

Leia múltiplos valores com o mesmo nome

Ao contrário dos botões de rádio, caixas de seleção com o mesmo name podem ser selecionadas juntas. Seus valores se repetem sob um mesmo nome, então leia todos eles. Use getAll em uma instância JavaScript FormData e verifique as regras do seu framework de servidor para lidar com valores múltiplos.

name identifica o campo; value é o que ele envia quando selecionado. Omitir o valor usa a string padrão on, portanto, especifique valores para distinguir as opções. Dê a cada caixa de seleção um id único para seu rótulo.

Exemplo completo: seleção múltipla, verificações obrigatórias e entradas excluídas

Salve este código como checkbox-demo.html e abra-o em um navegador. Ele exibe as entradas reais do formulário em vez de enviá-las para um servidor. Compare como uma opção desabilitada é excluída mesmo quando marcada.

<!doctype html>
<html lang="pt">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Valores enviados pelas caixas</title>
  <style>pre { white-space: pre-wrap; overflow-wrap: anywhere; }</style>
</head>
<body>
  <h1>Prática de caixas de seleção</h1>
  <form id="demo">
    <fieldset>
      <legend>Cores desejadas (seleção múltipla)</legend>
      <input type="checkbox" id="blue" name="color" value="blue" checked>
      <label for="blue">Azul</label>
      <input type="checkbox" id="red" name="color" value="red">
      <label for="red">Vermelho</label>
      <input type="checkbox" id="locked" name="color" value="green" checked disabled>
      <label for="locked">Verde (desativado)</label>
    </fieldset>
    <p>
      <input type="checkbox" id="ready" name="ready" value="yes" required>
      <label for="ready">Pronto para a prática (obrigatório)</label>
    </p>
    <button type="submit">Mostrar valores</button>
    <button type="reset">Vermelhoefinir</button>
    <button type="button" id="partial">Exibir Azul como parcialmente selecionado</button>
  </form>
  <pre id="result" aria-live="polite"></pre>
  <script>
    const form = document.getElementById('demo');
    const result = document.getElementById('result');
    const blue = document.getElementById('blue');
    form.addEventListener('submit', (event) => {
      event.preventDefault();
      result.textContent = JSON.stringify(Array.from(new FormData(form).entries()), null, 2);
    });
    document.getElementById('partial').addEventListener('click', () => {
      blue.indeterminate = true;
    });
    form.addEventListener('reset', () => {
      result.textContent = '';
      blue.indeterminate = false;
    });
  </script>
</body>
</html>

1. Enviar sem selecionar a caixa de prontidão: a validação obrigatória bloqueia o envio.
2. Selecione prontidão e Vermelho, depois envie. A saída contém color=blue, color=red e ready=yes; o Verde desabilitado é excluído.
3. Desmarque Azul e Vermelho e envie novamente. As entradas color desaparecem e só resta ready=yes.
4. O reset restaura Azul e Verde como marcados, enquanto Vermelho e prontidão voltam desmarcados.

Distinga entre marcado, obrigatório e indefinido

O atributo checked fornece a seleção inicial. Leia o estado atual usando a propriedade JavaScript checked. checked="false" ainda tem o atributo presente; omita-o para uma caixa inicialmente desmarcada. Reset restaura os valores iniciais em vez de limpar todas as caixas.

Uma checkbox com required deve estar marcada. Isso não significa que qualquer checkbox compartilhando o mesmo nome seja suficiente. Uma condição de “pelo menos uma dessas” precisa de validação e orientação separadas.

indeterminate é uma propriedade do JavaScript que exibe um estado de seleção parcial. Não é definida através de um atributo HTML e é independente de checked, que determina o envio. Após redefinir, pressione o botão de exibição parcial, selecione a caixa de prontidão necessária e inspecione os valores: azul ainda é enviado. A exibição parcial não limpa checked nem cria um terceiro valor enviado.

Trate valores ausentes e múltiplos no servidor

Tratar cada opção desmarcada ausente como um erro, ou ler apenas o último valor de um nome repetido, pode alterar o significado pretendido. Diferencie “nada selecionado” de uma solicitação inválida usando as regras da sua aplicação e valide os valores permitidos no servidor.

O PHP pode receber name="color[]" como um array, mas isso segue as regras do analisador do servidor. Um navegador não envia um objeto de array universal para todas as linguagens de programação. Verifique se o valor recebido é um array e trate valores ausentes, arrays aninhados e valores não permitidos. Consulte a documentação PHP sobre variáveis externas para regras de análise e a referência MDN para caixas de seleção sobre o comportamento das caixas de seleção.