> ## Documentation Index
> Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkbox
> Checkbox inputs for binary or multiple selections.
export const ComponentPreview = ({json, height, resizable, bare, hideJson, playground, children}) => {
const hostRef = React.useRef(null);
const handleRef = React.useRef(null);
const cardRef = React.useRef(null);
const containerRef = React.useRef(null);
const [previewWidth, setPreviewWidth] = React.useState(null);
const [isDragging, setIsDragging] = React.useState(false);
const [playgroundHref, setPlaygroundHref] = React.useState(null);
React.useEffect(function () {
if (!playground) return;
var isLocal = location.hostname === "localhost" || location.hostname === "127.0.0.1";
var path = isLocal ? "/playground" : "/docs/playground";
var url = new URL(path, window.location.href);
url.hash = "code=" + playground;
setPlaygroundHref(url.href);
}, [playground]);
var jsonStr = typeof json === "string" ? json : JSON.stringify(json, null, 2);
React.useEffect(function () {
if (cardRef.current) {
var card = cardRef.current.closest(".group");
if (card) card.classList.remove("group");
}
var host = hostRef.current;
if (!host || !json) return;
function mount() {
if (!window.__prefab || !host) return;
var dark = document.documentElement.classList.contains("dark");
handleRef.current = window.__prefab.mountPreview(host, jsonStr, {
dark: dark
});
if (bare && host.shadowRoot) {
var m = host.shadowRoot.querySelector("[data-prefab-mount]");
if (m) m.style.background = "transparent";
}
}
if (window.__prefab) {
mount();
} else {
if (!window.__prefabLoading) {
if (!window.__prefabReady) {
var s = document.createElement("script");
s.src = "/renderer.js";
document.head.appendChild(s);
}
window.__prefabLoading = new Promise(function (resolve) {
function check() {
if (window.__prefabReady) {
window.__prefabReady.then(resolve);
} else {
setTimeout(check, 10);
}
}
check();
});
}
window.__prefabLoading.then(mount);
}
var observer = new MutationObserver(function () {
var dark = document.documentElement.classList.contains("dark");
if (handleRef.current) handleRef.current.setDark(dark);
});
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ["class"]
});
return function () {
observer.disconnect();
if (handleRef.current) {
handleRef.current.unmount();
handleRef.current = null;
}
};
}, [json]);
function startResize(e) {
e.preventDefault();
var startX = e.clientX;
var startW = hostRef.current ? hostRef.current.offsetWidth : 0;
var maxW = containerRef.current ? containerRef.current.offsetWidth - 10 : startW;
setIsDragging(true);
function onMove(ev) {
var w = Math.max(260, Math.min(startW + (ev.clientX - startX), maxW));
setPreviewWidth(w);
}
function onUp() {
document.removeEventListener("mousemove", onMove);
document.removeEventListener("mouseup", onUp);
setIsDragging(false);
}
document.addEventListener("mousemove", onMove);
document.addEventListener("mouseup", onUp);
}
if (bare) {
return ;
}
if (resizable) {
return
{previewWidth &&
{previewWidth}px
}
{playgroundHref && }
{children}
;
}
return
{playgroundHref && }
{children}
;
};
Checkboxes let users select one or more options from a set.
## Basic Usage
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Checkbox
Checkbox(label="Accept terms and conditions")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"name": "checkbox_1",
"value": false,
"type": "Checkbox",
"label": "Accept terms and conditions",
"disabled": false,
"required": false
},
"state": {"checkbox_1": false}
}
```
## Checked State
Pass `value=True` to render a checkbox already ticked. Use this for options that should be opted in by default, like a newsletter subscription the user can clear if they'd rather not.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Checkbox
Checkbox(label="Subscribe to newsletter", value=True)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"name": "checkbox_2",
"value": true,
"type": "Checkbox",
"label": "Subscribe to newsletter",
"disabled": false,
"required": false
},
"state": {"checkbox_2": true}
}
```
## Multiple Checkboxes
Each checkbox binds to its own independent state key, so toggling one never affects the others. Reach for a set of checkboxes when the choices are not mutually exclusive and any combination is valid — unlike a grouped Radio, where selecting one option clears the rest.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Checkbox,
Column,
)
with Column(gap=3, css_class="w-fit mx-auto"):
Checkbox(label="Email notifications", value=True)
Checkbox(label="SMS notifications")
Checkbox(label="Push notifications", value=True)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "checkbox_3",
"value": true,
"type": "Checkbox",
"label": "Email notifications",
"disabled": false,
"required": false
},
{
"name": "checkbox_4",
"value": false,
"type": "Checkbox",
"label": "SMS notifications",
"disabled": false,
"required": false
},
{
"name": "checkbox_5",
"value": true,
"type": "Checkbox",
"label": "Push notifications",
"disabled": false,
"required": false
}
]
},
"state": {"checkbox_3": true, "checkbox_4": false, "checkbox_5": true}
}
```
## With Actions
The `on_change` parameter runs actions when the checkbox is toggled. `$event` is `true` when checked, `false` when unchecked:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Checkbox, Column, Text
from prefab_ui.actions import SetState
from prefab_ui.rx import EVENT, Rx
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" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "accepted",
"value": false,
"type": "Checkbox",
"label": "Accept terms",
"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}
}
```
## With Disabled State
Set `disabled=True` to show an option that can't be changed right now while still keeping its checked or unchecked value visible. This is the right state for a choice that's locked by a permission or a prerequisite the user hasn't met yet.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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", value=True, disabled=True)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "checkbox_6",
"value": false,
"type": "Checkbox",
"label": "Enabled option",
"disabled": false,
"required": false
},
{
"name": "checkbox_7",
"value": false,
"type": "Checkbox",
"label": "Disabled option",
"disabled": true,
"required": false
},
{
"name": "checkbox_8",
"value": true,
"type": "Checkbox",
"label": "Disabled & checked",
"disabled": true,
"required": false
}
]
},
"state": {"checkbox_6": false, "checkbox_7": false, "checkbox_8": true}
}
```
## 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:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Checkbox, Input, Label, Row
with Row(gap=4, align="center"):
cb = Checkbox(label="Enable Infinite Improbability Drive", value=True)
Label("Drive status:")
Input(value=cb.rx.then("Engaged", "Disengaged"), read_only=True)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4 items-center",
"type": "Row",
"children": [
{
"name": "checkbox_9",
"value": true,
"type": "Checkbox",
"label": "Enable Infinite Improbability Drive",
"disabled": false,
"required": false
},
{"type": "Label", "text": "Drive status:", "optional": false},
{
"name": "input_2",
"value": "{{ checkbox_9 ? 'Engaged' : 'Disengaged' }}",
"type": "Input",
"inputType": "text",
"disabled": false,
"readOnly": true,
"required": false
}
]
},
"state": {"checkbox_9": true}
}
```
Toggle the checkbox and the input updates to reflect the current state.
## API Reference
Label text displayed next to the checkbox.
Whether the checkbox is initially checked.
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.
Whether the checkbox is non-interactive.
Whether the checkbox is required for form submission.
Action(s) to execute when toggled. `$event` is `true` when checked, `false` when unchecked.
Additional Tailwind CSS classes appended to the component's built-in styles.
## Protocol Reference
```json Checkbox theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Checkbox",
"id?": "string",
"onMount?": "any",
"name?": "string",
"value?": "boolean | string",
"label?": "string",
"disabled?": false,
"required?": false,
"onChange?": "Action | Action[]",
"cssClass?": "string"
}
```
For the complete protocol schema, see [Checkbox](/protocol/checkbox).