---
title: Checkbox
description: Checkbox inputs for binary or multiple selections.
icon: square-check
---

import { ComponentPreview } from "/snippets/component-preview.mdx";

Checkboxes let users select one or more options from a set.

## Basic Usage

<ComponentPreview json={{"view":{"type":"Checkbox","label":"Accept terms and conditions","checked":false,"name":"checkbox-1","disabled":false,"required":false}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox

Checkbox(label="Accept terms and conditions")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Checkbox",
    "label": "Accept terms and conditions",
    "checked": false,
    "name": "checkbox-1",
    "disabled": false,
    "required": false
  }
}
```
</CodeGroup>
</ComponentPreview>

## Checked State

<ComponentPreview json={{"view":{"type":"Checkbox","label":"Subscribe to newsletter","checked":true,"name":"checkbox-2","disabled":false,"required":false}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox

Checkbox(label="Subscribe to newsletter", checked=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Checkbox",
    "label": "Subscribe to newsletter",
    "checked": true,
    "name": "checkbox-2",
    "disabled": false,
    "required": false
  }
}
```
</CodeGroup>
</ComponentPreview>

## Multiple Checkboxes

<ComponentPreview json={{"view":{"cssClass":"gap-3 w-fit mx-auto","type":"Column","children":[{"type":"Checkbox","label":"Email notifications","checked":true,"name":"checkbox-3","disabled":false,"required":false},{"type":"Checkbox","label":"SMS notifications","checked":false,"name":"checkbox-4","disabled":false,"required":false},{"type":"Checkbox","label":"Push notifications","checked":true,"name":"checkbox-5","disabled":false,"required":false}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Checkbox,
    Column,
)

with Column(gap=3, css_class="w-fit mx-auto"):
    Checkbox(label="Email notifications", checked=True)
    Checkbox(label="SMS notifications")
    Checkbox(label="Push notifications", checked=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-3 w-fit mx-auto",
    "type": "Column",
    "children": [
      {
        "type": "Checkbox",
        "label": "Email notifications",
        "checked": true,
        "name": "checkbox-3",
        "disabled": false,
        "required": false
      },
      {
        "type": "Checkbox",
        "label": "SMS notifications",
        "checked": false,
        "name": "checkbox-4",
        "disabled": false,
        "required": false
      },
      {
        "type": "Checkbox",
        "label": "Push notifications",
        "checked": true,
        "name": "checkbox-5",
        "disabled": false,
        "required": false
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Actions

The `on_change` parameter runs actions when the checkbox is toggled. `$event` is `true` when checked, `false` when unchecked:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"type":"Checkbox","label":"Accept terms","checked":false,"name":"accepted","disabled":false,"required":false,"onChange":{"action":"setState","key":"message","value":"{{ $event ? 'Thank you!' : 'Please accept to continue' }}"}},{"cssClass":"text-muted-foreground","content":"{{ message | 'Check the box' }}","type":"Text"}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox, Column, Text
from prefab_ui.actions import SetState

with Column(gap=4):
    Checkbox(
        label="Accept terms",
        name="accepted",
        on_change=SetState(
            "message",
            "{{ $event ? 'Thank you!' : 'Please accept to continue' }}",
        ),
    )
    Text(
        "{{ message | 'Check the box' }}",
        css_class="text-muted-foreground",
    )
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "type": "Checkbox",
        "label": "Accept terms",
        "checked": false,
        "name": "accepted",
        "disabled": false,
        "required": false,
        "onChange": {
          "action": "setState",
          "key": "message",
          "value": "{{ $event ? 'Thank you!' : 'Please accept to continue' }}"
        }
      },
      {
        "cssClass": "text-muted-foreground",
        "content": "{{ message | 'Check the box' }}",
        "type": "Text"
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Disabled State

<ComponentPreview json={{"view":{"cssClass":"gap-3 w-fit mx-auto","type":"Column","children":[{"type":"Checkbox","label":"Enabled option","checked":false,"name":"checkbox-6","disabled":false,"required":false},{"type":"Checkbox","label":"Disabled option","checked":false,"name":"checkbox-7","disabled":true,"required":false},{"type":"Checkbox","label":"Disabled & checked","checked":true,"name":"checkbox-8","disabled":true,"required":false}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Checkbox,
    Column,
)

with Column(gap=3, css_class="w-fit mx-auto"):
    Checkbox(label="Enabled option")
    Checkbox(label="Disabled option", disabled=True)
    Checkbox(label="Disabled & checked", checked=True, disabled=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-3 w-fit mx-auto",
    "type": "Column",
    "children": [
      {
        "type": "Checkbox",
        "label": "Enabled option",
        "checked": false,
        "name": "checkbox-6",
        "disabled": false,
        "required": false
      },
      {
        "type": "Checkbox",
        "label": "Disabled option",
        "checked": false,
        "name": "checkbox-7",
        "disabled": true,
        "required": false
      },
      {
        "type": "Checkbox",
        "label": "Disabled & checked",
        "checked": true,
        "name": "checkbox-8",
        "disabled": true,
        "required": false
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Checkbox Parameters">

<ParamField body="label" type="str | None" default="None">
  Label text displayed next to the checkbox.
</ParamField>

<ParamField body="checked" type="bool" default="False">
  Whether the checkbox is initially checked.
</ParamField>

<ParamField body="name" type="str | None" default="None">
  State key for the checkbox's checked state. Auto-generated if not provided. Use `.rx` to reference the checkbox's boolean value in other components.
</ParamField>

<ParamField body="value" type="str | None" default="None">
  Form value when checked.
</ParamField>

<ParamField body="disabled" type="bool" default="False">
  Whether the checkbox is non-interactive.
</ParamField>

<ParamField body="required" type="bool" default="False">
  Whether the checkbox is required for form submission.
</ParamField>

<ParamField body="on_change" type="Action | list[Action] | None" default="None">
  Action(s) to execute when toggled. `$event` is `true` when checked, `false` when unchecked.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes appended to the component's built-in styles.
</ParamField>
</Card>

## Protocol Reference

```json Checkbox
{
  "type": "Checkbox",
  "label?": "string",
  "checked?": false,
  "name?": "string",
  "value?": "string",
  "disabled?": false,
  "required?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Checkbox](/protocol/checkbox).
