Checkbox Group

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-checkbox-group é o contêiner semântico e orquestrador de múltiplos controles br-checkbox que pertencem a um mesmo contexto ou pergunta em formulários do GovBR-DS.

Para que serve

• Agrupamento semântico e acessibilidade: Cria a estrutura recomendada de fieldset e legend para leitores de tela, garantindo que o contexto da pergunta seja anunciado antes de cada opção individual.
• Validação conjunta: Permite coordenar regras de validação em grupo (como exigir uma quantidade mínima ou máxima de checkboxes selecionados).
• Alinhamento e padronização visual: Organiza os checkboxes vertical ou horizontalmente conforme o leiaute da interface.

Quando utilizar

• Utilize quando:
  • Existirem duas ou mais opções em checkbox que respondem à mesma pergunta ou pertencem ao mesmo conjunto lógico de preferências.
  • For necessário aplicar rótulo geral e mensagens de validação ao grupo completo de escolhas.
• Evite e prefira outro componente quando:
  • Houver apenas um único checkbox independente (ex.: aceite de termos): use br-checkbox isoladamente.
  • A seleção for de escolha única (mutuamente exclusiva): use br-radio-group.

Estrutura e Slots

O br-checkbox-group atua como container orquestrador:

• default: Slot onde devem ser inseridos os elementos br-checkbox que compõem o grupo.
• feedback: Slot opcional para mensagem de erro ou orientação de validação associada ao grupo todo.

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

PadrãoTodos selecionadosSeleção parcialOrientação horizontalDesabilitado

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

customId

Atributo	custom-id
Descrição	Identificador único do controlador.
Tipo	string
Valor padrão	generateUniqueId('br-checkbox-group')

disabled

Atributo	disabled
Descrição	Desabilita o controlador e os checkboxes contidos no grupo.
Tipo	boolean
Valor padrão	false

indeterminate

Atributo	indeterminate
Descrição	Define o estado indeterminado inicial do grupo.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Texto descritivo do grupo.
Tipo	string
Valor padrão	---

orientation

Atributo	orientation
Descrição	Orientação visual das opções. Valores inválidos usam vertical.
Tipo	"horizontal" | "vertical"
Valor padrão	'vertical'

selectAllLabel

Atributo	select-all-label
Descrição	Rótulo para marcar todos os checkboxes.
Tipo	string
Valor padrão	'Selecionar tudo'

unselectAllLabel

Atributo	unselect-all-label
Descrição	Rótulo para desmarcar todos os checkboxes.
Tipo	string
Valor padrão	'Desselecionar tudo'

Slots

Nome	Descrição
"default"	Slot para adicionar os checkboxes controlados pelo grupo.

Dependências

Usado por

• br-checkgroup

Depende de

• br-checkbox

Gráfico