---
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":{"name":"checkbox_1","type":"Checkbox","label":"Accept terms and conditions","checked":false,"disabled":false,"required":false},"state":{"checkbox_1":false}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ2hlY2tib3gKCkNoZWNrYm94KGxhYmVsPSJBY2NlcHQgdGVybXMgYW5kIGNvbmRpdGlvbnMiKQo=">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox

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

## Checked State

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

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

## Multiple Checkboxes

<ComponentPreview json={{"view":{"cssClass":"gap-3 w-fit mx-auto","type":"Column","children":[{"name":"checkbox_3","type":"Checkbox","label":"Email notifications","checked":true,"disabled":false,"required":false},{"name":"checkbox_4","type":"Checkbox","label":"SMS notifications","checked":false,"disabled":false,"required":false},{"name":"checkbox_5","type":"Checkbox","label":"Push notifications","checked":true,"disabled":false,"required":false}]},"state":{"checkbox_3":true,"checkbox_4":false,"checkbox_5":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgKAogICAgQ2hlY2tib3gsCiAgICBDb2x1bW4sCikKCndpdGggQ29sdW1uKGdhcD0zLCBjc3NfY2xhc3M9InctZml0IG14LWF1dG8iKToKICAgIENoZWNrYm94KGxhYmVsPSJFbWFpbCBub3RpZmljYXRpb25zIiwgY2hlY2tlZD1UcnVlKQogICAgQ2hlY2tib3gobGFiZWw9IlNNUyBub3RpZmljYXRpb25zIikKICAgIENoZWNrYm94KGxhYmVsPSJQdXNoIG5vdGlmaWNhdGlvbnMiLCBjaGVja2VkPVRydWUpCg==">
<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": [
      {
        "name": "checkbox_3",
        "type": "Checkbox",
        "label": "Email notifications",
        "checked": true,
        "disabled": false,
        "required": false
      },
      {
        "name": "checkbox_4",
        "type": "Checkbox",
        "label": "SMS notifications",
        "checked": false,
        "disabled": false,
        "required": false
      },
      {
        "name": "checkbox_5",
        "type": "Checkbox",
        "label": "Push notifications",
        "checked": true,
        "disabled": false,
        "required": false
      }
    ]
  },
  "state": {"checkbox_3": true, "checkbox_4": false, "checkbox_5": true}
}
```
</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 w-fit mx-auto","type":"Column","children":[{"name":"accepted","type":"Checkbox","label":"Accept terms","checked":false,"disabled":false,"required":false,"onChange":{"action":"setState","key":"message","value":"{{ $event ? 'Thank you!' : 'Please accept to continue' }}"}},{"cssClass":"text-muted-foreground","content":"{{ message | default:'Check the box' }}","type":"Text"}]},"state":{"accepted":false}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox, Column, Text
from prefab_ui.actions import SetState
from prefab_ui.rx import Rx

event = Rx("$event")
message = Rx("message")

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

## With Disabled State

<ComponentPreview json={{"view":{"cssClass":"gap-3 w-fit mx-auto","type":"Column","children":[{"name":"checkbox_6","type":"Checkbox","label":"Enabled option","checked":false,"disabled":false,"required":false},{"name":"checkbox_7","type":"Checkbox","label":"Disabled option","checked":false,"disabled":true,"required":false},{"name":"checkbox_8","type":"Checkbox","label":"Disabled & checked","checked":true,"disabled":true,"required":false}]},"state":{"checkbox_6":false,"checkbox_7":false,"checkbox_8":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgKAogICAgQ2hlY2tib3gsCiAgICBDb2x1bW4sCikKCndpdGggQ29sdW1uKGdhcD0zLCBjc3NfY2xhc3M9InctZml0IG14LWF1dG8iKToKICAgIENoZWNrYm94KGxhYmVsPSJFbmFibGVkIG9wdGlvbiIpCiAgICBDaGVja2JveChsYWJlbD0iRGlzYWJsZWQgb3B0aW9uIiwgZGlzYWJsZWQ9VHJ1ZSkKICAgIENoZWNrYm94KGxhYmVsPSJEaXNhYmxlZCAmIGNoZWNrZWQiLCBjaGVja2VkPVRydWUsIGRpc2FibGVkPVRydWUpCg==">
<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": [
      {
        "name": "checkbox_6",
        "type": "Checkbox",
        "label": "Enabled option",
        "checked": false,
        "disabled": false,
        "required": false
      },
      {
        "name": "checkbox_7",
        "type": "Checkbox",
        "label": "Disabled option",
        "checked": false,
        "disabled": true,
        "required": false
      },
      {
        "name": "checkbox_8",
        "type": "Checkbox",
        "label": "Disabled & checked",
        "checked": true,
        "disabled": true,
        "required": false
      }
    ]
  },
  "state": {"checkbox_6": false, "checkbox_7": false, "checkbox_8": true}
}
```
</CodeGroup>
</ComponentPreview>

## Reading the Value

Use `.rx` to get a reactive reference to the checkbox's boolean state. The `.then()` pipe converts `true`/`false` into display-friendly strings:

<ComponentPreview json={{"view":{"cssClass":"gap-4 items-center","type":"Row","children":[{"name":"checkbox_9","type":"Checkbox","label":"Enable Infinite Improbability Drive","checked":true,"disabled":false,"required":false},{"type":"Label","text":"Drive status:"},{"name":"input_2","type":"Input","inputType":"text","value":"{{ checkbox_9 ? 'Engaged' : 'Disengaged' }}","disabled":false,"readOnly":true,"required":false}]},"state":{"checkbox_9":true}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ2hlY2tib3gsIElucHV0LCBMYWJlbCwgUm93Cgp3aXRoIFJvdyhnYXA9NCwgYWxpZ249ImNlbnRlciIpOgogICAgY2IgPSBDaGVja2JveChsYWJlbD0iRW5hYmxlIEluZmluaXRlIEltcHJvYmFiaWxpdHkgRHJpdmUiLCBjaGVja2VkPVRydWUpCiAgICBMYWJlbCgiRHJpdmUgc3RhdHVzOiIpCiAgICBJbnB1dCh2YWx1ZT1jYi5yeC50aGVuKCJFbmdhZ2VkIiwgIkRpc2VuZ2FnZWQiKSwgcmVhZF9vbmx5PVRydWUpCg==">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Checkbox, Input, Label, Row

with Row(gap=4, align="center"):
    cb = Checkbox(label="Enable Infinite Improbability Drive", checked=True)
    Label("Drive status:")
    Input(value=cb.rx.then("Engaged", "Disengaged"), read_only=True)
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4 items-center",
    "type": "Row",
    "children": [
      {
        "name": "checkbox_9",
        "type": "Checkbox",
        "label": "Enable Infinite Improbability Drive",
        "checked": true,
        "disabled": false,
        "required": false
      },
      {"type": "Label", "text": "Drive status:"},
      {
        "name": "input_2",
        "type": "Input",
        "inputType": "text",
        "value": "{{ checkbox_9 ? 'Engaged' : 'Disengaged' }}",
        "disabled": false,
        "readOnly": true,
        "required": false
      }
    ]
  },
  "state": {"checkbox_9": true}
}
```
</CodeGroup>
</ComponentPreview>

Toggle the checkbox and the input updates to reflect the current state.

## 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).
