Checkbox

Apresentação

O componente Checkbox é responsável por criar caixas de seleção que permitem ao usuário selecionar uma ou mais opções. Ele é ideal para formulários, listas de seleção e qualquer situação que exija uma escolha binária (sim/não) ou múltipla.

Quando usar

• Em formulários de seleção múltipla
• Para aceitar termos e condições
• Para selecionar preferências
• Para marcar itens em listas
• Para ativar/desativar opções
• Para selecionar filtros
• Para escolher categorias
• Para marcar tarefas concluídas
• Para selecionar itens em tabelas
• Para ativar configurações

Forma básica de uso

import { Checkbox } from 'eitri-luminus';

// Checkbox básico
<Checkbox />

// Checkbox com label
<div className="form-control">
  <label className="label cursor-pointer">
    <span className="label-text">Lembrar-me</span>
    <Checkbox />
  </label>
</div>

// Checkbox com diferentes tamanhos
<Checkbox className="checkbox-xs" />
<Checkbox className="checkbox-sm" />
<Checkbox className="checkbox-md" />
<Checkbox className="checkbox-lg" />

// Checkbox com diferentes cores
<Checkbox className="checkbox-primary" />
<Checkbox className="checkbox-secondary" />
<Checkbox className="checkbox-accent" />

// Checkbox desabilitado
<Checkbox disabled />

// Checkbox marcado por padrão
<Checkbox defaultChecked />

// Checkbox com evento de mudança
<Checkbox onChange={(e) => console.log(e.target.checked)} />

// Checkbox em um grupo
<div className="form-control">
  <label className="label cursor-pointer">
    <span className="label-text">Opção 1</span>
    <Checkbox name="grupo" value="1" />
  </label>
  <label className="label cursor-pointer">
    <span className="label-text">Opção 2</span>
    <Checkbox name="grupo" value="2" />
  </label>
  <label className="label cursor-pointer">
    <span className="label-text">Opção 3</span>
    <Checkbox name="grupo" value="3" />
  </label>
</div>

// Checkbox com métodos via ref
import { useRef } from 'react';

const MyComponent = () => {
  const checkboxRef = useRef<Checkbox>(null);

  const handleGetValue = () => {
    const isChecked = checkboxRef.current?.getValue();
    console.log('Checkbox está marcado:', isChecked);
  };

  const handleSetValue = (checked: boolean) => {
    checkboxRef.current?.setValue(checked);
  };

  const handleToggle = () => {
    checkboxRef.current?.toggle();
  };

  return (
    <div>
      <Checkbox ref={checkboxRef} onChange={(e) => console.log('Mudou:', e.target.checked)} />
      <button onClick={handleGetValue}>Verificar valor</button>
      <button onClick={() => handleSetValue(true)}>Marcar</button>
      <button onClick={() => handleSetValue(false)}>Desmarcar</button>
      <button onClick={handleToggle}>Alternar</button>
    </div>
  );
};

Métodos via Ref

O componente Checkbox expõe os seguintes métodos públicos que podem ser acessados através de uma ref:

Método	Tipo de Retorno	Descrição
getValue()	boolean	Retorna se o checkbox está marcado
setValue(checked: boolean)	void	Define se o checkbox está marcado
toggle()	void	Alterna o estado do checkbox (marca/desmarca)

Exemplo de uso dos métodos

import { useRef } from 'react';
import { Checkbox } from 'eitri-luminus';

const MyForm = () => {
  const termsCheckboxRef = useRef<Checkbox>(null);

  const handleAcceptAll = () => {
    // Marca todos os checkboxes de termos
    termsCheckboxRef.current?.setValue(true);
  };

  const handleRejectAll = () => {
    // Desmarca todos os checkboxes de termos
    termsCheckboxRef.current?.setValue(false);
  };

  const handleToggleTerms = () => {
    // Alterna o estado do checkbox de termos
    termsCheckboxRef.current?.toggle();
  };

  return (
    <div>
      <Checkbox 
        ref={termsCheckboxRef}
        onChange={(e) => console.log('Termos:', e.target.checked)}
      />
      <label>Eu aceito os termos e condições</label>
      <button onClick={handleAcceptAll}>Aceitar</button>
      <button onClick={handleRejectAll}>Rejeitar</button>
      <button onClick={handleToggleTerms}>Alternar</button>
    </div>
  );
};

Propriedades

O componente Checkbox herda todas as propriedades de um input HTML padrão, exceto 'type', 'dangerouslySetInnerHTML' e 'children', além das propriedades comuns da biblioteca. As principais propriedades incluem:

Propriedade	Tipo	Descrição
checked	boolean	Estado de seleção do checkbox
defaultChecked	boolean	Estado inicial de seleção
disabled	boolean	Desabilita o checkbox
name	string	Nome do campo no formulário
value	string	Valor do checkbox
onChange	function	Função chamada ao mudar o estado
className	string	Classes CSS adicionais
id	string	Identificador único do componente

Heranças

O componente Checkbox herda todas as propriedades comuns da biblioteca através da interface CommonProps, que inclui:

• Propriedades de estilo (margin, padding, etc)
• Propriedades de layout (flex, grid, etc)
• Propriedades de posicionamento
• Propriedades de acessibilidade
• Propriedades de identificação (id, data-e)

Observações

• O componente usa a classe 'checkbox' para estilização base
• Suporta diferentes tamanhos (xs, sm, md, lg)
• Suporta diferentes cores (primary, secondary, accent)
• É possível personalizar a aparência usando classes do Tailwind
• O componente é responsivo por padrão
• Mantém a semântica HTML apropriada
• Pode ser usado em grupos de seleção
• Suporta estados desabilitado e marcado
• É especialmente útil para seleções múltiplas
• Pode ser combinado com outros componentes
• Suporta eventos de mudança
• Mantém o tipo "checkbox" por padrão
• Pode ser usado em formulários
• Suporta validação de formulários
• Suporta métodos públicos via ref para controle programático (getValue, setValue, toggle)