Pharos
Navegar componentes
← Componentes

CheckboxInput

CheckboxExemplo
CheckboxInput alterna um único valor ligado/desligado. Use para configurações como "Ativar notificações", aceite de termos ou escolhas de opt-in. Para múltiplos checkboxes em um grupo, use CheckboxList.
Importação
import {CheckboxInput} from '@pharos-ds/core/CheckboxInput';

Exemplos

Área interativa

size
isDisabled
isLoading
Código
import {CheckboxInput} from '@pharos-ds/core/CheckboxInput';

<CheckboxInput
  label="Aceito os termos"
  size="md"
  isDisabled={false}
  isLoading={false}
 />

Boas práticas

  • Faça: Sempre forneça um rótulo visível para que o usuário saiba o que está alternando. Use isLabelHidden apenas quando o contexto ao redor torna isso óbvio.
  • Faça: Adicione uma description para escolhas que precisam de contexto extra, como explicar o que "Compartilhar dados de uso" realmente compartilha.
  • Faça: Use o estado indeterminado para checkboxes "selecionar todos" quando apenas alguns itens de um grupo estão selecionados.
  • Evite: Use um checkbox para escolhas mutuamente exclusivas; use RadioList quando apenas uma opção pode ser selecionada.
  • Evite: Use um checkbox para ações que entram em vigor imediatamente; use um toggle switch ou botão.
  • Evite: Envolva um checkbox desabilitado em Tooltip para explicar por que está desabilitado; controles desabilitados absorvem os eventos de hover que o wrapper precisa. Use a prop disabledMessage.

Props

PropTipoPadrãoDescrição
refReact.Ref<HTMLInputElement>—Ref encaminhada para o elemento <input> subjacente.
label *string—Texto do rótulo do checkbox (sempre renderizado para acessibilidade).
isLabelHiddenbooleanfalseSe o rótulo deve ser ocultado visualmente (ainda acessível a leitores de tela).
descriptionstring—Texto de description exibido abaixo do rótulo.
value *boolean | 'indeterminate'—Se o checkbox está marcado, desmarcado ou indeterminado.
onChange(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void—Callback disparado quando o estado do checkbox muda.
changeAction(checked: boolean, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>—Ação assíncrona na mudança. Dispara após onChange se não for prevenida. Mostra spinner de loading enquanto pendente.
isLoadingbooleanfalseSe o checkbox está em estado de loading. Mostra spinner e impede interação.
isDisabledbooleanfalseSe o checkbox está desabilitado.
htmlNamestring—Atributo HTML name do input checkbox subjacente, útil para envio de formulários (envia "on" quando marcado).
disabledMessagestring—Explica por que o checkbox está desabilitado. Com isDisabled, mostra tooltip em hover/foco por teclado e mantém o checkbox focável via aria-disabled (alternância permanece bloqueada). Use isso em vez de envolver um CheckboxInput desabilitado em Tooltip. Controles desabilitados absorvem os eventos de hover que um Tooltip externo precisa.
isReadOnlybooleanfalseSe o checkbox é somente leitura. Exibe o estado atual com opacidade total, mas impede interação. Diferente de `isDisabled`, checkboxes read-only não ficam visualmente esmaecidos.
isOptionalbooleanfalseSe o campo é opcional. Mutuamente exclusivo com isRequired.
isRequiredbooleanfalseSe o checkbox é obrigatório. Mutuamente exclusivo com isOptional.
size'sm' | 'md''md'Tamanho do checkbox. sm para layouts compactos, md para o padrão.
onFocus(e: FocusEvent<HTMLInputElement>) => void—Callback disparado quando o checkbox recebe foco.
onBlur(e: FocusEvent<HTMLInputElement>) => void—Callback disparado quando o checkbox perde foco.
labelIconIconType—Ícone exibido antes do texto do rótulo. Veja `pharos docs icons` para nomes semânticos válidos.
status{ type: 'error' | 'warning' | 'success', message: string }—Indicador de status. Exibe uma caixa de mensagem colorida abaixo do checkbox e define aria-invalid para erros.
widthSizeValue—Largura do campo (número = pixels, string usada como está, ex. "100%"). Dimensiona o campo inteiro (rótulo, controle e status) para mantê-los alinhados.
Pacote: @pharos-ds/core · Import: @pharos-ds/core/CheckboxInput
CheckboxInput · Pharos