Checkbox

Overview

The Checkbox component allows users to select one or more options from a set, providing a binary choice with visual feedback for checked, unchecked, and indeterminate states. Built on Base UI primitives, it features customizable sizes and URL state management for seamless integration with modern web applications.

Usage

import { Checkbox } from "@tilt-legal/cubitt-components/primitives";

<Checkbox />

Using Cubitt's URL-state hooks, you can sync the checkbox state with the URL by providing a paramName:

// Boolean state synced with ?terms=true
<Checkbox paramName="terms" defaultChecked={false} />

// Indeterminate state synced with ?partial=indeterminate
<Checkbox paramName="partial" defaultIndeterminate={true} />

// With label and URL state:
<Label orientation="horizontal">
  <Checkbox paramName="newsletter" defaultChecked={false} />
  Subscribe to newsletter
</Label>

// Advanced options:
<Checkbox
  paramName="feature"
  paramClearOnDefault={true}    // Remove param when value equals default
  paramDebounce={100}           // Debounce URL updates
  onUrlValueChange={(checked) => console.log('Feature enabled:', checked)}
  defaultChecked={false}
/>

Examples

Checked by Default

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <Label orientation="horizontal">
      <Checkbox defaultChecked />
      Checked by default
    </Label>
  );
}

Indeterminate

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <Label orientation="horizontal">
      <Checkbox defaultIndeterminate />
      Indeterminate state
    </Label>
  );
}

Disabled

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <div className="flex flex-col gap-4">
      <Label orientation="horizontal">
        <Checkbox disabled />
        Disabled (unchecked)
      </Label>
      <Label orientation="horizontal">
        <Checkbox disabled defaultChecked />
        Disabled (checked)
      </Label>
    </div>
  );
}

With Description

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <Label orientation="horizontal">
      <Checkbox />
      <div className="flex flex-col gap-1.5 pt-0.5">
        <p>Accept terms and conditions</p>
        <p className="text-muted-foreground text-sm">
          By checking this box, you agree to our terms of service and privacy
          policy.
        </p>
      </div>
    </Label>
  );
}

Sizes

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <div className="flex items-center gap-6">
      <Label orientation="horizontal">
        <Checkbox size="sm" />
        Small
      </Label>
      <Label orientation="horizontal">
        <Checkbox size="md" />
        Medium
      </Label>
      <Label orientation="horizontal">
        <Checkbox size="lg" />
        Large
      </Label>
    </div>
  );
}

URL State

This example syncs with the URL parameter "demo-terms".

import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";

export default function Component() {
  return (
    <Label orientation="horizontal" className="gap-3">
      <Checkbox paramName="demo-terms" defaultChecked={false} />
      Accept terms and conditions
    </Label>
  );
}

API Reference

Checkbox

The root component for creating checkboxes with customizable sizes and URL state management.

Prop	Type	Default	Description
`checked`	`boolean`	-	The controlled checked state of the checkbox.
`defaultChecked`	`boolean`	`false`	The default checked state when uncontrolled.
`indeterminate`	`boolean`	-	Whether the checkbox is in an indeterminate state.
`defaultIndeterminate`	`boolean`	`false`	Whether the checkbox starts in an indeterminate state when uncontrolled.
`onCheckedChange`	`(checked: boolean, eventDetails) => void`	-	Callback fired when the checked state changes.
`disabled`	`boolean`	`false`	Whether the checkbox is disabled.
`required`	`boolean`	`false`	Whether the checkbox is required in a form.
`readOnly`	`boolean`	`false`	Whether the user should be unable to change the checkbox state.
`name`	`string`	-	The name of the checkbox when used in a form.
`value`	`string`	-	The value of the checkbox when used in a form.
`id`	`string`	-	The id attribute for the checkbox input.
`size`	`"sm"` \| `"md"` \| `"lg"`	`"md"`	The size of the checkbox.
`className`	`string`	-	Additional CSS classes to apply to the checkbox.
`inputRef`	`React.Ref<HTMLInputElement>`	-	A ref to access the hidden `<input>` element.

URL State Props

When provided with a paramName, the checkbox will sync its checked state with URL parameters via TanStack Router search params.

Prop	Type	Default	Description
`paramName`	`string`	-	URL parameter name for syncing state with URL. Enables URL state management.
`paramValue`	`boolean \| "indeterminate"`	-	Controlled value for the URL parameter.
`onUrlValueChange`	`(value: boolean \| "indeterminate" \| null) => void`	-	Callback when URL parameter value changes.
`paramClearOnDefault`	`boolean`	`true`	Remove URL param when value equals default.
`paramThrottle`	`number`	-	Throttle URL updates in milliseconds.
`paramDebounce`	`number`	-	Debounce URL updates in milliseconds.

Checkbox

URL State Management

On this page