componentes / checkbox

Checkbox

Checkbox accesible con etiqueta, texto de ayuda y de error, estado indeterminado y colores.

Cómo usar

Un `<input type="checkbox">` nativo (así que formularios, `ref` y teclado funcionan) con aspecto propio. Pasa `label` para que toda la fila sea clicable e `indeterminate` para un padre con solo algunos hijos marcados.

preview

Acepto los términos

NewsletterUn correo por semana

Seleccionar todo

Checkbox.tsx

import { Checkbox } from "vaiperui";
 
<Checkbox label="Acepto los términos" />
<Checkbox
  defaultChecked
  label="Newsletter"
  helperText="Un correo por semana"
/>
<Checkbox indeterminate label="Seleccionar todo" />

Colores

preview

primary

success

warning

danger

colores.tsx

<Checkbox defaultChecked variantColor="primary" label="primary" />
<Checkbox defaultChecked variantColor="success" label="success" />
<Checkbox defaultChecked variantColor="warning" label="warning" />
<Checkbox defaultChecked variantColor="danger" label="danger" />

Tamaños

preview

tamanos.tsx

<Checkbox defaultChecked size="sm" label="sm" />
<Checkbox defaultChecked size="md" label="md" />
<Checkbox defaultChecked size="lg" label="lg" />

Indeterminado

`indeterminate` muestra un guion, para un checkbox padre con solo algunos hijos marcados.

preview

Seleccionar todo

indeterminate

indeterminado.tsx

<Checkbox indeterminate label="Seleccionar todo" />

Estados

preview

ayudaDetalle extra

ayuda

errorEsto es obligatorio

error

deshabilitado

deshabilitado ✓

estados.tsx

<Checkbox label="ayuda" helperText="..." />
<Checkbox label="error" errorMessage="..." />
<Checkbox label="deshabilitado" disabled />
<Checkbox label="deshabilitado" disabled defaultChecked />

Color personalizado

`customColor` acepta cualquier color CSS, o un par `{ light, dark }`.

preview

Naranja

Violeta

color-personalizado.tsx

<Checkbox defaultChecked customColor="#ff6600" label="Naranja" />
<Checkbox defaultChecked customColor={{ light: "#7c3aed", dark: "#a78bfa" }} label="Violeta" />

Props

Prop	Valores	Predeterminado	Descripción
variantColor	primary \| success \| warning \| danger	primary	Color del estado marcado y del anillo de foco
customColor	string \| { light, dark }	ninguno	Cualquier color CSS (o un par por tema). Reemplaza a variantColor
size	sm \| md \| lg	md	Tamaño del control y del texto
radius	none \| sm \| md \| lg \| full	sm	Redondeo de las esquinas de la caja
animation	none \| smooth \| fast \| bounce	smooth	Transición al alternar
label	ReactNode	ninguno	Texto junto al control; al hacer clic se alterna
helperText	string	ninguno	Línea secundaria bajo la etiqueta
errorMessage	string	ninguno	Texto de error; su sola presencia fuerza el estado de error
indeterminate	boolean	false	Muestra un guion en lugar del check
(nativas)	InputHTMLAttributes<HTMLInputElement>	ninguno	checked, defaultChecked, onChange, name, value, disabled, required, aria-*, className, ref, etc.

Accesibilidad

Renderiza un `<input type="checkbox">` nativo (oculto visualmente, con la casilla personalizada dibujada encima), así que el rol, el cambio con Space y el comportamiento en formularios son nativos.
El `<label>` envuelve el input, así que el texto de la etiqueta le da nombre y toda la fila es clicable.
`indeterminate` define la propiedad `indeterminate` del DOM, que las tecnologías asistivas leen como "mixto".
`errorMessage` define `aria-invalid="true"`; `aria-describedby` apunta al error, o al `helperText` si no hay error.
Los iconos de check y guion son `aria-hidden`; el estado lo expone solo el input nativo.

Teclado

Tecla	Acción
Space	Alterna el checkbox.

Ten en cuenta

Sin `label`, pasa `aria-label`; el control no tiene otro nombre.
`indeterminate` es solo estado visual: el clic sigue resultando en marcado o desmarcado, y tú decides qué significa.