## Overview [#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 [#usage]
```tsx
import { Checkbox } from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
Using Cubitt's URL-state hooks, you can sync the checkbox state with the URL by providing a `paramName`:
```tsx
// Boolean state synced with ?terms=true
// Indeterminate state synced with ?partial=indeterminate
// With label and URL state:
// Advanced options:
console.log('Feature enabled:', checked)}
defaultChecked={false}
/>
```
## Examples [#examples]
### Checked by Default [#checked-by-default]
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### Indeterminate [#indeterminate]
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### Disabled [#disabled]
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### With Description [#with-description]
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### Sizes [#sizes]
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
### URL State [#url-state]
This example syncs with the URL parameter "demo-terms".
```tsx
import { Checkbox, Label } from "@tilt-legal/cubitt-components/primitives";
export default function Component() {
return (
);
}
```
## API Reference [#api-reference]
### Checkbox [#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` | - | A ref to access the hidden `` element. |
#### URL State Props [#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. |