Checkbox

2.5.1

Permite seleccionar una o varias opciones de una lista, de forma independiente entre sí.

Ver en Figma

Cuándo usar

Seleccionar ítems de una lista: elegir uno o varios elementos opcionales dentro de una lista de datos.
Activar filtros en simultáneo: habilitar varios atributos de un filtro o una búsqueda al mismo tiempo.
Seleccionar filas de una tabla: marcar múltiples filas para ejecutar acciones masivas.
Confirmar una aceptación: registrar el consentimiento a una condición puntual, como aceptar términos y condiciones.

Cuándo no usar

Elegir una opción excluyente: seleccionar una única opción entre varias mutuamente excluyentes. En su lugar, usar Radio.
Aplicar un cambio inmediato: activar o desactivar una configuración con efecto inmediato. En su lugar, usar Toggle.
Disparar una acción: ejecutar algo al instante en lugar de registrar una selección. En su lugar, usar Button.

Anatomía

Opción

Container: caja de selección que refleja el estado y recibe la interacción.
Icon: marca que aparece dentro del contenedor según el estado: un check cuando está marcado o una línea cuando es indeterminate.
Label: texto que describe la opción que representa el control.

Variantes

Apariencia

Opción

Primary: apariencia por defecto.

Opción

Danger: señala un error de validación en la selección. Ej.: un checkbox obligatorio que quedó sin marcar al enviar el formulario.

Generado por IA

Opción

aiGenerated: aplica un borde con degradé de IA para indicar que el valor fue sugerido por inteligencia artificial. Ej.: una opción precompletada por una sugerencia automática.

Estados

Aplicación

Suele aparecer en formularios, listas de opciones, paneles de configuración y filtros, junto a la etiqueta que describe la opción para que quede claro qué se está activando o desactivando.

Medios de pago aceptados

Tarjeta de crédito

Transferencia bancaria

Efectivo

Do and Don'ts

Accesibilidad

Label asociado: acompañar siempre el control con un label que describa la opción, para que lectores de pantalla anuncien de qué se trata.
Navegación por teclado: el checkbox es alcanzable con Tab y se marca o desmarca con la barra espaciadora.
Foco visible: el control muestra un anillo de foco al navegar con teclado, sin depender del puntero.
No depender solo del color: la apariencia danger se acompaña de un texto de error o ayuda, ya que el color por sí solo no comunica el problema.

Guía de contenido

El label del Checkbox describe qué se activa al seleccionarlo, no el estado técnico ni la acción de marcar. Si no funciona solo, sin depender de lo que lo rodea, hay que reescribirlo.

Reglas de contenido

Capitalización: primera letra siempre mayúscula. El label de grupo también va en sentence case, sin punto final.
Puntuación: sin punto ni coma al final. Excepción: los labels de aceptación de términos o políticas son oraciones completas y sí llevan punto final.
Framing positivo: describir lo que se activa, no lo que se evita. "Mostrar precios con IVA incluido", no "Ocultar precios sin IVA".
Autonomía del label: debe funcionar solo, sin depender del texto que lo rodea.
Orden: las opciones de una lista se ordenan con un criterio lógico (alfabético, numérico, temporal u otro criterio claro).
Forma verbal: con verbo ("Recibir notificaciones") o sin verbo ("Notificaciones por e-mail") son válidas ambas; mantener la misma forma dentro de un mismo grupo de opciones.
Aceptación de términos: "Acepto [términos/política]" o "Estoy de acuerdo con [términos/política]".

Casos críticos

Caso	Qué hacer
El label necesita más explicación	Agregar help text. No alargar el label ni usar un tooltip para información crítica.
Estado indeterminate (selección parcial de un grupo)	No escribir un label específico para ese estado; el estado visual ya lo comunica.
Selección masiva en una tabla	Sin label visible. Agregar un aria-label descriptivo, por ejemplo "Seleccionar todos los productos".

Implementación

Instalá el componente vía terminal.

npm install @nimbus-ds/components

import React from "react";
import { Checkbox } from "@nimbus-ds/components";

const Example: React.FC = () => <Checkbox name="my-checkbox" label="Label" />;

export default Example;

Props

Las propiedades adicionales se pasan al elemento <Checkbox>. Consultá la documentación del elemento input para ver la lista de atributos aceptados.

Componentes relacionados

Radio — Para seleccionar una sola opción entre varias mutuamente excluyentes.
Toggle — Para activar o desactivar una configuración con efecto inmediato.
Button — Para confirmar o disparar una acción, en lugar de marcar una opción.

Checkbox

Name	Type	Default	Description
name*	string		The name of the input element.
appearance	'danger' 'primary'	'neutral'	Change the visual style of the checkbox.
checked	boolean		Modifies true/false value of the native checkbox.
disabled	boolean		Modifies the native disabled state of the native checkbox.
indeterminate	boolean	'false'	If true, the component appears indeterminate. This does not set the native input element to indeterminate due to inconsistent behavior across browsers. However, we set a data-indeterminate attribute on the input.
label	string		Text to be rendered inside the component.
aiGenerated	boolean	'false'	Highlights the checkbox to indicate its value was generated by AI. Applies AI gradient border that persists regardless of checked state.

Checkbox.Skeleton

Name	Type	Description
width	string	Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
className	string
data-testid	string	This is an attribute used to identify a DOM node for testing purposes.

Ayudanos a mejorar la documentación

¿Encontraste un problema o tenés una sugerencia? Contanos.

Compartí tu opinión