Primitiveselection

Checkbox

Stable

Primitive de seleção binária, com estado misto para o caso de um pai que controla um grupo. Composto sobre Base UI Checkbox; a área tocável se estende além da caixa de 16px sem deslocar o layout ao redor.

Instalação

npx up-web-ds add checkbox

Gera check, minus para a biblioteca de ícones do projeto (components.json → iconLibrary).

Usage

Imports de Checkbox

import { Checkbox } from '@/components/ui/checkbox'
import { useId } from 'react'

Checkbox

1
2
3
4
5
6
7
8
9
10
11
12function PublishCheckbox() {
  const id = useId()

  return (
    <div className="flex items-center gap-3">
      <Checkbox id={id} defaultChecked />
      <label htmlFor={id} className="type-small font-medium">
        Publicar no registry
      </label>
    </div>
  )
}

Props

Props de Checkbox
Prop	Type	Default	Description
checked	`boolean`	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
className	`string \| ((state: CheckboxRootState) => string \| undefined)`	sem valor padrão	CSS class applied to the element, or a function that returns a class based on the component's state.
defaultChecked	`boolean`	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
form	`string`	sem valor padrão	Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
id	`string`	sem valor padrão	The id of the input element.
indeterminate	`boolean`	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
inputRef	`React.Ref<HTMLInputElement>`	sem valor padrão	A ref to access the hidden `<input>` element.
name	`string`	`undefined`	Identifies the field when a form is submitted.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
onCheckedChange	`((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void)`	sem valor padrão	Event handler called when the checkbox is ticked or unticked.
parent	`boolean`	`false`	Whether the checkbox controls a group of child checkboxes. Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).
readOnly	`boolean`	`false`	Whether the user should be unable to tick or untick the checkbox.
render	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, CheckboxRootState>`	sem valor padrão	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
required	`boolean`	`false`	Whether the user must tick the checkbox before submitting a form.
style	`React.CSSProperties \| ((state: CheckboxRootState) => React.CSSProperties \| undefined)`	sem valor padrão	Style applied to the element, or a function that returns a style object based on the component's state.
uncheckedValue	`string`	sem valor padrão	The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
value	`string`	sem valor padrão	The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".

Estende CheckboxPrimitive.Root.Props. Aceita também os atributos padrão de um elemento React (273 não listados).

Metadata

Notas de acessibilidade

Teclado e leitor de tela verificados por teste: alcançável por Tab, Space alterna, o papel é checkbox e aria-checked reporta true, false e mixed. Um checkbox desabilitado sai da sequência de tabulação e recusa a alternância; aria-invalid é exposto sem alterar o papel. Touch verificado em viewport de 375px com emulação de toque: o alvo mede 40x32 contra uma caixa visual de 16x16, acima do mínimo de 24x24 da WCAG 2.2 SC 2.5.8. Reduced motion verificado com prefers-reduced-motion: reduce — a única transição, a do anel de foco, não é movimento e permanece: remover uma transição de cor não acomoda ninguém e custa a única pista que o estado tem. Nenhum deslocamento existe aqui para ser desligado.

Classificação

Layer: Primitive
Domínio: Domain-free (compartilhado)
Categoria: selection
Status: Stable

Origem e distribuição

Fonte: shadcn registry / checkbox
Licença: MIT
URL: https://ui.shadcn.com/r/styles/base-vega/checkbox.json
Distribuição: Interna

Acessibilidade

Teclado: revisado
Leitor de tela: revisado
Touch: revisado
Reduced motion: revisado

Dependências

Pacotes: @base-ui/react
Ícones: check, minus
Construído sobre: Nenhum
Usado por: Questionnaire

Checkbox

Instalação

Preview

Basic

Default

Checked

Indeterminate

Disabled

Invalid

Parent And Children

All states

Usage

Props

Metadata

Notas de acessibilidade

Classificação

Origem e distribuição

Acessibilidade

Dependências