Checkbox
Caixa de marcação para aceitar termos, ativar uma opção ou escolher vários itens de uma lista.
'use client';
import { Checkbox } from '@/components/ui/checkbox';
export default function CheckboxDemo() {
return <Checkbox name="novidades">Quero receber novidades por e-mail</Checkbox>;
}Instalação
npx shadcn@latest add @lenstech/checkboxUso
import { Checkbox, CheckboxGroup } from "@/components/ui/checkbox"<Checkbox name="lgpd" isRequired>
Aceito a Política de Privacidade
</Checkbox>onChange recebe um boolean
onChange entrega true/false (e não o evento). Para controlar, use isSelected + onChange; para valor
inicial, defaultSelected. Em um CheckboxGroup, o grupo controla a seleção com value (array de strings).
Exemplos
Com descrição
'use client';
import { Checkbox } from '@/components/ui/checkbox';
export default function CheckboxDescription() {
return (
<Checkbox
name="lgpd"
className="max-w-sm"
description="Seus dados serão usados apenas para retornar o contato, conforme a LGPD."
>
Aceito a Política de Privacidade
</Checkbox>
);
}Desabilitado
'use client';
import { Checkbox } from '@/components/ui/checkbox';
export default function CheckboxDisabled() {
return (
<div className="flex flex-col gap-4">
<Checkbox isDisabled>Emitir boleto (indisponível no seu plano)</Checkbox>
<Checkbox isDisabled defaultSelected>
Backup diário (sempre ativo)
</Checkbox>
</div>
);
}Obrigatório
Com isRequired dentro de um Form, o envio é bloqueado até marcar. Tente enviar sem
marcar.
'use client';
import { Button } from '@/components/ui/button';
import { Checkbox } from '@/components/ui/checkbox';
import { Form } from '@/components/ui/form';
export default function CheckboxInvalid() {
return (
<Form onSubmit={(e) => e.preventDefault()} className="max-w-sm">
<Checkbox name="termos" isRequired errorMessage="Aceite os termos para continuar.">
Li e aceito os Termos de Uso
</Checkbox>
<Button type="submit" className="self-start">
Criar conta
</Button>
</Form>
);
}Grupo
CheckboxGroup junta várias opções sob um rótulo. Cada Checkbox precisa de value. Use
orientation="horizontal" para opções curtas.
'use client';
import { Checkbox, CheckboxGroup } from '@/components/ui/checkbox';
export default function CheckboxGroupExample() {
return (
<div className="flex flex-col gap-8">
<CheckboxGroup
name="servicos"
label="Quais serviços interessam?"
description="Selecione quantos quiser."
defaultValue={['site']}
>
<Checkbox value="site">Site institucional</Checkbox>
<Checkbox value="loja">Loja virtual</Checkbox>
<Checkbox value="sistema">Sistema de gestão</Checkbox>
</CheckboxGroup>
<CheckboxGroup
name="dias"
label="Dias de atendimento"
orientation="horizontal"
defaultValue={['seg', 'ter', 'qua', 'qui', 'sex']}
>
{['seg', 'ter', 'qua', 'qui', 'sex', 'sáb', 'dom'].map((dia) => (
<Checkbox key={dia} value={dia}>
{dia.charAt(0).toUpperCase() + dia.slice(1)}
</Checkbox>
))}
</CheckboxGroup>
</div>
);
}Selecionar todos (indeterminado)
isIndeterminate mostra um traço quando só parte dos itens está marcada.
'use client';
import { useState } from 'react';
import { Checkbox, CheckboxGroup } from '@/components/ui/checkbox';
const permissoes = [
{ id: 'agenda', label: 'Ver agenda' },
{ id: 'pacientes', label: 'Editar pacientes' },
{ id: 'financeiro', label: 'Acessar financeiro' },
];
export default function CheckboxIndeterminate() {
const [selecionadas, setSelecionadas] = useState<string[]>(['agenda']);
const todas = selecionadas.length === permissoes.length;
return (
<div className="flex flex-col gap-3">
<Checkbox
isSelected={todas}
isIndeterminate={selecionadas.length > 0 && !todas}
onChange={(marcado) => setSelecionadas(marcado ? permissoes.map((p) => p.id) : [])}
>
Todas as permissões
</Checkbox>
<CheckboxGroup aria-label="Permissões" value={selecionadas} onChange={setSelecionadas} className="pl-6">
{permissoes.map((p) => (
<Checkbox key={p.id} value={p.id}>
{p.label}
</Checkbox>
))}
</CheckboxGroup>
</div>
);
}Quando usar
- Use para aceites (termos, LGPD) e para escolher várias opções de uma lista curta.
- Não use para escolher uma opção entre várias — use
Radio Group. - Não use para configurações com efeito imediato (sem botão de salvar) — use
Switch. - Com muitas opções, prefira
SelectcomselectionMode="multiple"ouList Box.
API
Checkbox
Aceita todas as props do Checkbox do React Aria, mais:
Prop
Type
CheckboxGroup
Aceita todas as props do CheckboxGroup do React Aria, mais:
Prop
Type
Composição
CheckboxField, CheckboxButton e CheckboxIndicator são as peças usadas pelo Checkbox. Use-as para
layouts próprios (por exemplo, um checkbox dentro de um cartão).