---
title: Checkbox
description: Single checkbox control with card and list variants and custom true/false values.
sidebar:
  order: 6
search:
  tags: [boolean, checked, indeterminate, selection]
---

# Checkbox

> Single checkbox control with card and list variants and custom true/false values.

## Import

```tsx
import { Checkbox } from 'moraine'
```

## Slot Structure

Checkbox indicator with optional label and description.

```text
root
├── container
│   ├── input
│   └── control
│       └── indicator (optional)
└── wrapper (optional)
    ├── label (optional)
    └── description (optional)
```

## Examples

### Variants

List and card variants with start/end/hidden indicator positions.

```tsx
function Variants() {
  return (
    <div class="gap-8 grid sm:grid-cols-2">
      <div class="space-y-3">
        <Checkbox label="List / start" description="Default list style" defaultChecked />
        <Checkbox
          label="List / end"
          description="Indicator at the end"
          indicator="end"
          defaultChecked
        />
        <Checkbox
          label="List / hidden"
          description="Only text, no visible indicator"
          indicator="hidden"
          defaultChecked
        />
      </div>

      <div class="space-y-3">
        <Checkbox
          variant="card"
          label="Card variant"
          description="Whole card area is clickable"
          defaultChecked
        />
        <Checkbox
          variant="card"
          label="Card / end"
          description="Card with trailing indicator"
          indicator="end"
        />
        <Checkbox variant="card" label="Card / disabled" description="Disabled state" disabled />
      </div>
    </div>
  )
}
```

### Sizes

Scale from xs to xl with unified label spacing.

```tsx
function Sizes() {
  const SIZES: CheckboxSizeName[] = ['xs', 'sm', 'md', 'lg', 'xl']

  type CheckboxSizeName = Exclude<CheckboxT.Variant['size'], undefined>

  return (
    <div class="flex flex-col gap-2 max-w-xl">
      <For each={SIZES}>
        {(size) => (
          <Checkbox
            size={size}
            label={`Size ${size}`}
            description={`Checkbox size: ${size}`}
            defaultChecked={size === 'md' || size === 'xl'}
          />
        )}
      </For>
    </div>
  )
}
```

### Indeterminate + Custom Icons

Custom checked/indeterminate icons with controlled indeterminate transition.

```tsx
function IndeterminateCustomIcons() {
  const [indeterminate, setIndeterminate] = createSignal<'indeterminate' | boolean>('indeterminate')

  return (
    <div class="max-w-xl space-y-3">
      <Checkbox
        label="Permissions"
        description={`Current: ${String(indeterminate())}`}
        checked={indeterminate()}
        onChange={setIndeterminate}
        checkedIcon="i-lucide:check-check"
        indeterminateIcon="i-lucide:ellipsis"
      />
      <div class="flex flex-wrap gap-2">
        <Button variant="outline" size="sm" onClick={() => setIndeterminate('indeterminate')}>
          Set indeterminate
        </Button>
        <Button variant="outline" size="sm" onClick={() => setIndeterminate(true)}>
          Set checked
        </Button>
        <Button variant="outline" size="sm" onClick={() => setIndeterminate(false)}>
          Set unchecked
        </Button>
      </div>
    </div>
  )
}
```

### Custom True/False Values

Map checked state to domain values instead of boolean.

```tsx
function CustomTrueFalseValues() {
  const INDICATORS: CheckboxIndicatorName[] = ['start', 'end', 'hidden']

  const [featureFlag, setFeatureFlag] = createSignal<'enabled' | 'disabled'>('enabled')

  type CheckboxIndicatorName = Exclude<CheckboxT.Variant['indicator'], undefined>

  return (
    <div class="max-w-xl space-y-3">
      <Checkbox<'enabled', 'disabled'>
        label="Feature flag"
        description="Controlled with custom values"
        trueValue="enabled"
        falseValue="disabled"
        checked={featureFlag()}
        onChange={setFeatureFlag}
        indicator="end"
      />
      <p class="text-xs text-muted-foreground">Current value: {featureFlag()}</p>

      <div class="p-3 b-(1 border) rounded-lg">
        <p class="text-xs text-muted-foreground mb-2">Indicator matrix:</p>
        <div class="flex flex-col gap-2">
          <For each={INDICATORS}>
            {(indicator) => (
              <Checkbox
                indicator={indicator}
                label={`Indicator ${indicator}`}
                description="Uncontrolled"
                defaultChecked
              />
            )}
          </For>
        </div>
      </div>
    </div>
  )
}
```

## API Reference

### Attributes

#### `root`

Labelable checkbox wrapper that coordinates input, indicator, and text content.

#### `control`

Visible checkbox control users recognize as the toggle target.

##### Data Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| data-checked | string \| undefined | Present when the item is checked or selected. |
| data-disabled | string \| undefined | Present when the component or item is disabled. |
| data-indeterminate | string \| undefined | State or slot attribute exposed for styling hooks and selectors. |
| data-invalid | string \| undefined | Present when the field has a validation error. |
| data-readonly | string \| undefined | Present when the field is read-only. |
| data-required | string \| undefined | Present when the field is required. |

##### ARIA Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| aria-checked | boolean \| string \| undefined | Accessibility attribute forwarded by the rendered component. |
| aria-disabled | boolean \| string \| undefined | Indicates that the control is disabled. |
| aria-labelledby | boolean \| string \| undefined | References the element that labels the control or region. |
| aria-readonly | boolean \| string \| undefined | Indicates that the control value cannot be changed by the user. |
| aria-required | boolean \| string \| undefined | Indicates that user input is required. |
| role | string | Defines the semantic role exposed to assistive technology. |

#### `indicator`

Visual checked or indeterminate state layer inside the control.

##### Data Attributes

| Attribute | Type | Description |
| --- | --- | --- |
| data-checked | string \| undefined | Present when the item is checked or selected. |
| data-disabled | string \| undefined | Present when the component or item is disabled. |
| data-indeterminate | string \| undefined | State or slot attribute exposed for styling hooks and selectors. |
| data-readonly | string \| undefined | Present when the field is read-only. |
| data-required | string \| undefined | Present when the field is required. |

#### `icon`

Check or indeterminate icon rendered for the current state.

#### `wrapper`

Inner layout wrapper used by card and list checkbox variants.

#### `label`

Primary checkbox label text.

#### `description`

Supporting text associated with the checkbox.

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked | "indeterminate" \| TTrue \| TFalse \| undefined | — | Whether the checkbox is checked (controlled). |
| checkedIcon | IconT.Name | icon-check | Icon to show when checked. |
| class | ClassValue | — | Class applied to the component root or trigger element. |
| classes | CheckboxT.Classes \| undefined | — | — |
| defaultChecked | boolean \| "indeterminate" \| undefined | false | Whether the checkbox is checked by default (uncontrolled). |
| description | JSX.Element | — | Description text for the checkbox. |
| disabled | boolean \| undefined | false | Whether the input is disabled. |
| falseValue | TFalse \| undefined | false | Value to use when the checkbox is unchecked. |
| formFieldBind | boolean \| undefined | true | Whether to bind the checkbox value to the parent FormField. |
| id | string \| undefined | — | The ID of the input element. |
| indeterminate | boolean \| undefined | false | Whether the checkbox is in an indeterminate state. |
| indeterminateIcon | IconT.Name | icon-minus | Icon to show when indeterminate. |
| indicator | "hidden" \| "end" \| "start" \| undefined | — | — |
| label | JSX.Element | — | Label for the checkbox. |
| name | string \| undefined | — | The name of the input element, used for form submission. |
| onChange | ((value: TTrue \| TFalse) => void) \| undefined | — | Callback when the checked state changes. |
| onPointerDown | JSX.EventHandlerUnion<HTMLButtonElement, PointerEvent> \| undefined | — | Pointer down handler for the checkbox control. |
| readOnly | boolean \| undefined | false | Whether the input is read-only. |
| ref | JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined | — | — |
| required | boolean \| undefined | false | Whether the input is required. |
| size | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined | — | — |
| style | JSX.CSSProperties \| undefined | — | — |
| styles | CheckboxT.Styles \| undefined | — | — |
| trueValue | TTrue \| undefined | true | Value to use when the checkbox is checked. |
| value | string \| undefined | on | Native value submitted when the checkbox is checked. |
| variant | "list" \| "card" \| undefined | — | — |

### ARIA

Accessibility attributes and roles emitted by the component markup.

| Attribute | Type | Description |
| --- | --- | --- |
| aria-checked | boolean \| string \| undefined | Accessibility attribute forwarded by the rendered component. |
| aria-disabled | boolean \| string \| undefined | Indicates that the control is disabled. |
| aria-hidden | boolean \| string \| undefined | Hides decorative content from assistive technology. |
| aria-labelledby | boolean \| string \| undefined | References the element that labels the control or region. |
| aria-readonly | boolean \| string \| undefined | Indicates that the control value cannot be changed by the user. |
| aria-required | boolean \| string \| undefined | Indicates that user input is required. |
| role | string | Defines the semantic role exposed to assistive technology. |

### Data Attributes

State and slot attributes exposed for styling hooks and selectors.

| Attribute | Type | Description |
| --- | --- | --- |
| data-checked | string \| undefined | Present when the item is checked or selected. |
| data-disabled | string \| undefined | Present when the component or item is disabled. |
| data-indeterminate | string \| undefined | State or slot attribute exposed for styling hooks and selectors. |
| data-invalid | string \| undefined | Present when the field has a validation error. |
| data-readonly | string \| undefined | Present when the field is read-only. |
| data-required | string \| undefined | Present when the field is required. |
| data-slot | string | Identifies the rendered slot for styling hooks and selectors. |