메인 콘텐츠로 이동

Checkbox

A control that lets users toggle a boolean or intermediate state.

Overview

The Checkbox component allows users to select or deselect an option. It supports three states: on, off, and intermediate (indeterminate). Use it in forms, filter panels, and multi-selection scenarios.

  • Checkbox supports both controlled (status + onChange) and uncontrolled (defaultStatus) modes.
  • Use the intermediate state for "select all" patterns where only some children are selected.
  • For mutually exclusive choices, use RadioGroup instead.

Accessibility

  • Renders with role="checkbox" and aria-checked states for assistive technologies.
  • Space toggles the checkbox. Tab moves focus between checkboxes.
  • The intermediate state maps to aria-checked="mixed", communicating a partial selection to assistive technologies.
  • When label is provided, it is automatically associated with the checkbox for screen readers.
  • When disabled, the checkbox is visually dimmed and excluded from keyboard navigation.

Import

import { Checkbox } from "@cocso-ui/react";

Default

A basic checkbox controlled with local state. Use defaultStatus for uncontrolled usage.

"use client";

import { Checkbox } from "@cocso-ui/react";
import { useState } from "react";

export default function CheckboxDefault() {
  const [status, setStatus] = useState<"on" | "off" | "intermediate">("off");

  return (
    <div className="flex flex-col gap-4 p-4">
      <Checkbox label="Accept terms and conditions" onChange={setStatus} status={status} />
    </div>
  );
}

Size

Three sizes are available. Choose based on surrounding layout density.

"use client";

import { Checkbox } from "@cocso-ui/react";

export default function CheckboxSizes() {
  return (
    <div className="flex flex-col gap-4 p-4">
      <Checkbox label="Large checkbox" size="large" status="on" />
      <Checkbox label="Medium checkbox" size="medium" status="on" />
      <Checkbox label="Small checkbox" size="small" status="on" />
    </div>
  );
}

States

The checkbox supports on, off, and intermediate states. Use disabled to prevent interaction.

"use client";

import { Checkbox } from "@cocso-ui/react";

export default function CheckboxStates() {
  return (
    <div className="flex flex-col gap-4 p-4">
      <Checkbox label="Checked" status="on" />
      <Checkbox label="Unchecked" status="off" />
      <Checkbox label="Intermediate" status="intermediate" />
      <Checkbox disabled label="Disabled" status="on" />
    </div>
  );
}

API Reference

PropTypeDefaultDescription
status"on" | "off" | "intermediate"-The current checked state (controlled mode). `"on"` shows a checkmark, `"off"` shows an empty box, and `"intermediate"` shows a dash for partial selection.
defaultStatus"on" | "off" | "intermediate""off"The initial checked state (uncontrolled mode). The component manages its own state internally after mount.
onChange(status: "on" | "off") => void-Callback invoked when the user toggles the checkbox. Receives `"on"` or `"off"` — the `"intermediate"` state is only settable via the `status` prop. Works in both controlled and uncontrolled modes.
labelstring-Label text displayed next to the checkbox, automatically associated for screen reader accessibility.
size"large" | "medium" | "small""medium"Controls the checkbox dimensions and label font size. Use `large` for touch-friendly interfaces and `small` for compact layouts.
disabledbooleanfalsePrevents interaction and visually dims the checkbox. Disabled checkboxes are excluded from keyboard navigation.
idstring-The HTML `id` attribute. Auto-generated when not provided, maintaining the label-checkbox association.