Checkbox

Tipo: Core

DesignersFigma Design System 2.0
Devs · HTML/CSSmds-styles Storybook com classes e exemplos
Devs · Angularmds-angular Storybook com inputs e outputs

Definição Funcional

O Checkbox permite que o usuário selecione um ou mais itens de uma lista, ou alterne entre dois estados mutuamente exclusivos (ativado/desativado) para uma única opção independente.

Diretrizes de Comportamento

Independência: Cada caixa de seleção opera de forma independente; selecionar uma opção não deve desmarcar outra na mesma lista.
Rótulos Claros: O texto associado deve ser positivo e descrever claramente o que acontece quando marcado.
- Ruim: Não enviar notificação.
- Melhor: Enviar notificação.
Vá Direto ao Ponto: Use Caixa de Sentença para os rótulos. Apenas a primeira letra e nomes próprios em maiúsculas.
Agrupamento: Se houver uma lista longa, use um Checkbox “Mestre” no topo para permitir “Selecionar todos”.
Feedback Imediato: A alteração do estado deve ser visualmente clara, mas a aplicação da ação (como excluir itens selecionados) geralmente requer um botão de confirmação separado.

Exemplos de Escrita (Dos & Don’ts)

Contexto Logístico	Estilo Incorreto (Prolixo/Negativo)	Estilo UX (Conciso/Direto)
Filtro de Status	Eu quero ver apenas pedidos que já saíram	Pedidos enviados
Termos de Uso	Você aceita os termos e condições?	Aceito os termos e condições
Seguro de Carga	Deseja que a carga não fique sem seguro?	Incluir seguro de carga

Para desenvolvedores

Tudo abaixo é lido do código (stories, SCSS e componentes Angular) a cada npm run docs:sync — se algo estiver diferente do que você vê no projeto, o código é quem manda.

HTML/CSS (mds-styles)

Exemplo

Story Default do Storybook:

<div class="mds-checkbox mds-checkbox--single">
      <label class="mds-checkbox__wrap">
        <input type="checkbox" class="mds-checkbox__input"  >
        <div class="mds-checkbox__field">
          <i data-lucide="check" width="24" height="24" class="mds-icon d-inline-flex align-items-center justify-content-center mds-checkbox__field__check mds-icon--md"></i>
        </div>
        <span class="mds-checkbox__label">Checkbox Label</span>
      </label>
    </div>

Variações e opções

Opções do painel de controles do Storybook — escolha um valor lá para ver o resultado ao vivo. As classes CSS correspondentes estão na lista abaixo.

Opção	Valores	Padrão no exemplo
`checked`	`true` · `false`	`false`
`disabled`	`true` · `false`	—

Classes CSS

Lidas do SCSS (src/scss) — só aparece aqui o que realmente existe.

Tipo	Classes
Bloco	`.mds-checkbox`
Elementos	`.mds-checkbox__field` `.mds-checkbox__field__check` `.mds-checkbox__input` `.mds-checkbox__label` `.mds-checkbox__wrap`
Modificadores	`.mds-checkbox--group` `.mds-checkbox--lg` `.mds-checkbox--loading` `.mds-checkbox--sm` `.mds-checkbox--switch` `.mds-checkbox--xs`

Angular (mds-angular)

Seletor

mds-checkbox

Uma caixa de seleção é um controle de entrada que permite ao usuário selecionar uma ou mais opções de uma série de escolhas.

Inputs

Input	Tipo	Padrão	Descrição
`formControl`	`UntypedFormControl \| undefined`	`undefined`	FormControl do campo
`additionalClass`	`string`	`''`	Classe adicional
`className`	`string`	`''`	Classe CSS customizada adicionada ao host
`label`	`string`	`''`	Label do checkbox
`size`	`MdsSizesSmall`	`'md'`	Tamanhos para o checkbox do tipo `group`
`mode`	`MdsCheckboxModes`	`'single'`	Tipo de checkbox: * `single` - normal * `group` - grupo de seleção (estilo botão) * `switch` - Interruptor - liga e desliga
`icon`	`MdsIconAlias \| undefined`	`undefined`	Icone do para o checkbox do tipo `group`
`iconSize`	`MdsIconSizes`	`'md'`	Tamanho do icone.
`name`	`string`	`'opcao'`	Nome do campo
`required`	`boolean`	`false`	Campo requerido
`disabled`	`boolean`	`false`	Campo desativado
`checked` ⇄	`boolean`	`false`	Campo checado
`labelPosition`	`MdsCheckboxLabelPositions`	`'right'`	Posição do label com relação ao campo
`loading`	`boolean`	`false`	Exibe loading de carregando

⇄ = binding bidirecional ([(input)]).

Outputs

Output	Payload	Descrição
`onChange`	`boolean`	Eventos

Slots

Conteúdo projetado com o atributo data-position:

data-position="after-label"
data-position="after-content"
data-position="content-right"
data-position="after-switch"
data-position="switch-bottom"
data-position="switch-right"

Visão ao vivo

Checkbox — Figma (Design System 2.0) ↗