Docs executáveis de HTML: Checkbox

Q: Como fazer uma checkbox no HTML?

Use dentro de um label: I agree . O label deixa o texto clicável também.

Q: Como deixar uma checkbox marcada por padrão?

Adicione o atributo checked: . O que conta é a presença dele, então checked="false" ainda marca a caixa. No JavaScript, defina box.checked = true ou false.

Q: Como pegar o valor de uma checkbox no JavaScript?

Leia box.checked, que é true ou false. box.value é o valor que ela enviaria, e continua o mesmo com a caixa marcada ou não. Escute o evento change para reagir quando ela for alternada.

Q: Como mudar a cor de uma checkbox?

Defina accent-color nela: input[type=checkbox] { accent-color: #16a34a; }. Para uma aparência totalmente personalizada, defina appearance: none e desenhe a caixa e o visto você mesmo com CSS.

Como fazer uma checkbox no HTML

Uma checkbox é um <input type="checkbox">. Coloque-a dentro de um <label> com o seu texto, para que clicar no texto também a alterne. Marque uma ou as duas caixas e aperte Save para ver o que o formulário envia:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Checkbox</title>
</head>
<body>
  <form>
    <p><label><input type="checkbox" name="newsletter" value="yes"> Send me the newsletter</label></p>
    <p><label><input type="checkbox" name="updates" checked> Product updates</label></p>
    <button type="submit">Save</button>
  </form>
</body>
</html>

No estado padrão, o formulário envia só updates=on. Duas regras explicam isso:

Uma caixa marcada envia name=value. A segunda caixa não tem value, então envia o padrão, on.
Uma caixa desmarcada não envia nada. Nem newsletter=no, nem um valor vazio: o nome simplesmente não aparece nos dados.

checked no HTML define o estado inicial. Como todo atributo booleano, o que conta é a presença dele: checked="false" ainda marca a caixa.

Atributos da checkbox

Atributo	Faz
`name`	A chave enviada quando marcada
`value`	O que é enviado quando marcada (padrão `on`)
`checked`	Marcada quando a página carrega
`required`	O formulário não é enviado até esta caixa ser marcada
`disabled`	Não pode ser alternada e não é enviada

Um grupo de checkboxes

Para "escolha quantos quiser", dê a todas as caixas o mesmo name e um value diferente. Envolva-as num <fieldset> com uma <legend> para que o grupo tenha um nome:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Checkbox group</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    fieldset { border: 1px solid #9ca3af; border-radius: 8px; }
    label { display: block; margin: 4px 0; }
  </style>
</head>
<body>
  <form>
    <fieldset>
      <legend>Topics you like</legend>
      <label><input type="checkbox" name="topic" value="html" checked> HTML</label>
      <label><input type="checkbox" name="topic" value="css" checked> CSS</label>
      <label><input type="checkbox" name="topic" value="js"> JavaScript</label>
    </fieldset>
    <p><button type="submit">Save</button></p>
  </form>
</body>
</html>

O formulário envia topic=html e topic=css: o mesmo nome duas vezes. A maioria dos frameworks de servidor consegue ler isso como uma lista. O PHP é a exceção: ele fica só com o último, a não ser que o nome termine com colchetes, name="topic[]". No JavaScript, new FormData(form).getAll('topic') retorna ['html', 'css'].

Enviando um valor quando a caixa está desmarcada

Quando o servidor precisa de um "não" explícito, coloque um input oculto com o mesmo nome antes da checkbox. Desmarcada, só o valor oculto é enviado; marcada, os dois são enviados e o servidor fica com o último:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unchecked value</title>
</head>
<body>
  <form>
    <input type="hidden" name="marketing" value="no">
    <label><input type="checkbox" name="marketing" value="yes"> Marketing emails</label>
    <p>
      <label><input type="checkbox" name="terms" value="accepted" required> I accept the terms</label>
    </p>
    <button type="submit">Continue</button>
  </form>
</body>
</html>

Aperte Continue: o formulário se recusa até a caixa dos termos ser marcada, porque ela é required. Depois ele envia marketing=no e terms=accepted, ou marketing=no, marketing=yes e terms=accepted com a primeira caixa marcada. Frameworks como o Rails geram exatamente esse par com input oculto. Verifique como o seu servidor lê um nome repetido antes de contar com isso.

Selecionar todos e o estado indeterminate

Uma checkbox tem uma terceira aparência, um traço, para "algumas, mas não todas". Ela só existe no JavaScript: defina box.indeterminate = true. Uma caixa de "selecionar todos" a usa quando algumas das caixas que controla estão marcadas:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Select all</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    ul { list-style: none; padding-inline-start: 24px; margin: 4px 0; }
  </style>
</head>
<body>
  <label><input type="checkbox" id="all"> Select all</label>
  <ul>
    <li><label><input type="checkbox" class="item" checked> Email</label></li>
    <li><label><input type="checkbox" class="item"> SMS</label></li>
    <li><label><input type="checkbox" class="item"> Push</label></li>
  </ul>

  <script>
    const all = document.querySelector('#all');
    const items = [...document.querySelectorAll('.item')];

    const sync = () => {
      const count = items.filter((box) => box.checked).length;
      all.checked = count === items.length;
      all.indeterminate = count > 0 && count < items.length;
    };

    all.addEventListener('change', () => {
      items.forEach((box) => { box.checked = all.checked; });
    });
    items.forEach((box) => box.addEventListener('change', sync));
    sync();
  </script>
</body>
</html>

indeterminate só muda a aparência (e o que os leitores de tela anunciam: "misto" ou "parcialmente marcado"). Por baixo, a caixa continua marcada ou desmarcada, e é isso que o formulário envia. Clicar numa caixa indeterminate tira o traço e a alterna.

Use o evento change para reagir a uma checkbox, e leia box.checked para saber o estado. box.value não muda quando a caixa é alternada.

Estilizando checkboxes

A mudança mais rápida é accent-color, que muda a cor da checkbox nativa e mantém todo o seu comportamento. Para uma aparência completamente diferente, appearance: none remove o desenho nativo e deixa você estilizar o input como qualquer caixa:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Checkbox styles</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    label { display: flex; align-items: center; gap: 8px; margin-bottom: 10px; }
    .accent { accent-color: #16a34a; width: 20px; height: 20px; }

    .custom {
      appearance: none;
      width: 20px;
      height: 20px;
      margin: 0;
      border: 2px solid #6b7280;
      border-radius: 5px;
      display: grid;
      place-content: center;
    }
    .custom::before {
      content: "";
      width: 10px;
      height: 6px;
      border: 3px solid #fff;
      border-top: 0;
      border-right: 0;
      transform: rotate(-45deg) translate(1px, -1px);
      visibility: hidden;
    }
    .custom:checked { background: #2563eb; border-color: #2563eb; }
    .custom:checked::before { visibility: visible; }
    .custom:focus-visible { outline: 3px solid #f59e0b; outline-offset: 2px; }
  </style>
</head>
<body>
  <label><input type="checkbox" class="accent" checked> accent-color</label>
  <label><input type="checkbox" class="custom" checked> appearance: none</label>
  <label><input type="checkbox" class="custom"> appearance: none, unchecked</label>
</body>
</html>

A caixa personalizada continua sendo uma checkbox de verdade: alterna com clique e Espaço, é enviada com o formulário e é anunciada como checkbox. Desenhe-a com :checked e mantenha um estilo :focus-visible, porque sem o desenho nativo não existe contorno de foco que você mesmo não tenha adicionado.

Um toggle switch

Um switch é uma checkbox que significa "ligado ou desligado agora" em vez de "incluir isto". Desenhe-o com appearance: none e adicione role="switch" para que os leitores de tela anunciem um switch ligado ou desligado em vez de uma checkbox marcada:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Toggle switch</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    label { display: inline-flex; align-items: center; gap: 10px; }
    .switch {
      appearance: none;
      margin: 0;
      width: 44px;
      height: 24px;
      border-radius: 12px;
      background: #9ca3af;
      position: relative;
      cursor: pointer;
      transition: background 0.2s;
    }
    .switch::before {
      content: "";
      position: absolute;
      top: 3px;
      inset-inline-start: 3px;
      width: 18px;
      height: 18px;
      border-radius: 50%;
      background: #fff;
      transition: inset-inline-start 0.2s;
    }
    .switch:checked { background: #16a34a; }
    .switch:checked::before { inset-inline-start: 23px; }
    .switch:focus-visible { outline: 3px solid #f59e0b; outline-offset: 2px; }
  </style>
</head>
<body>
  <label><input type="checkbox" class="switch" role="switch" name="dark" checked> Dark mode</label>
</body>
</html>

inset-inline-start posiciona o botão a partir do início da linha, então o switch desliza para o outro lado em páginas da direita para a esquerda, como deve ser. Para escolhas de sim ou não agrupadas em que só uma pode ser escolhida, veja radio button no HTML.

Erros comuns

Esperar false de uma caixa desmarcada. Nada é enviado. Trate um nome ausente como "desligado" no servidor, ou adicione o input oculto.
checked="false". Ainda marca a caixa. Remova o atributo.
Uma checkbox sem label, ou com um texto ao lado que não é um <label>. A caixinha vira o único alvo de clique e os leitores de tela anunciam "checkbox" sem nome. Veja label no HTML.
Esquecer o value, e toda caixa de um grupo envia on sem que o servidor consiga diferenciá-las.
Ler box.value para saber se está marcada. Use box.checked.
Checkboxes para "escolha uma". É para isso que servem os radio buttons.

Perguntas frequentes

Como fazer uma checkbox no HTML?

Use <input type="checkbox"> dentro de um label: <label><input type="checkbox" name="terms" value="yes"> I agree</label>. O label deixa o texto clicável também.

Como deixar uma checkbox marcada por padrão?

Adicione o atributo checked: <input type="checkbox" name="news" checked>. O que conta é a presença dele, então checked="false" ainda marca a caixa. No JavaScript, defina box.checked = true ou false.

Que valor uma checkbox desmarcada envia?

Nenhum. Uma checkbox desmarcada fica totalmente de fora dos dados enviados. Uma marcada envia o seu value, ou on se não tiver value. Se o servidor precisa de um "não" explícito, coloque um input oculto com o mesmo nome antes da checkbox.

Como pegar o valor de uma checkbox no JavaScript?

Leia box.checked, que é true ou false. box.value é o valor que ela enviaria, e continua o mesmo com a caixa marcada ou não. Escute o evento change para reagir quando ela for alternada.

Como mudar a cor de uma checkbox?

Defina accent-color nela: input[type=checkbox] { accent-color: #16a34a; }. Para uma aparência totalmente personalizada, defina appearance: none e desenhe a caixa e o visto você mesmo com CSS.

Conceitos relacionados