Skip to main content

​
Import

from reflex_ui import checkbox

​
Description

A checkbox component for binary or indeterminate state selection with optional label support.

​
Basic Usage

checkbox(label="Accept terms")
checkbox(checked=State.accepted, on_checked_change=State.set_accepted)
checkbox(label="Indeterminate", indeterminate=True)

​
Props

​
label
str | Component
Optional label text or component to display next to the checkbox.
​
checked
Var[bool] | bool
Whether the checkbox is currently ticked (controlled).
​
default_checked
Var[bool] | bool
default:"False"
Whether the checkbox is initially ticked (uncontrolled).
​
indeterminate
Var[bool] | bool
default:"False"
Whether the checkbox is in a mixed state: neither ticked nor unticked.
​
disabled
Var[bool] | bool
default:"False"
Whether the component should ignore user interaction.
​
required
Var[bool] | bool
default:"False"
Whether the checkbox is required.
​
read_only
Var[bool] | bool
default:"False"
Whether the user should be unable to tick or untick the checkbox.
​
name
Var[str] | str
Identifies the field when a form is submitted.
​
value
Var[str] | str
The value of the selected checkbox.
​
unchecked_value
Var[str] | str
The value of the checkbox when unchecked. Used for form submission when unchecked.
​
native_button
Var[bool] | bool
default:"True"
Whether the component renders a native button element when replacing via render prop.
​
parent
Var[bool] | bool
default:"False"
Whether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group.

​
Event Handlers

​
on_checked_change
EventType[()] | EventType[bool] | EventType[bool, dict]
Event handler called when the checkbox is ticked or unticked.
​
on_click
EventType[()] | EventType[PointerEventInfo]
Fired when the checkbox is clicked.
​
on_focus
EventType[()]
Fired when the checkbox receives focus.
​
on_blur
EventType[()]
Fired when the checkbox loses focus.

​
Subcomponents

​
checkbox.root

The root checkbox component without label. 
checkbox.root(
    checkbox.indicator(),
    checked=State.value,
    on_checked_change=State.set_value,
    **props
) -> CheckboxRoot

​
checkbox.indicator

The indicator that shows whether the checkbox is checked. 
checkbox.indicator(
    custom_icon,  # Optional custom icon
    keep_mounted=False,
    **props
) -> CheckboxIndicator
​
keep_mounted
Var[bool] | bool
default:"True"
Whether to keep the HTML element in the DOM when the checkbox is unchecked. When False, allows exit animations.

​
Class Names Reference

checkbox.class_names.ROOT       # Checkbox root classes
checkbox.class_names.INDICATOR  # Indicator classes
checkbox.class_names.LABEL      # Label classes
checkbox.class_names.CONTAINER  # Container classes

​
ROOT Class

"flex size-4 items-center justify-center rounded-[4px] data-[checked]:bg-primary-9 data-[unchecked]:border data-[unchecked]:border-secondary-8 data-[disabled]:cursor-not-allowed data-[disabled]:border data-[disabled]:border-secondary-4 data-[disabled]:bg-secondary-3 hover:bg-secondary-3 transition-colors cursor-default"

​
INDICATOR Class

"flex text-primary-contrast data-[unchecked]:hidden data-[disabled]:text-secondary-8"

​
LABEL Class

"text-sm text-secondary-12 font-medium flex items-center gap-2"

​
Styling

Custom styling can be applied via class_name or style props: 
checkbox(
    label="Custom",
    class_name="custom-checkbox"
)

​
Method Signatures

​
HighLevelCheckbox.create

@classmethod
def create(
    cls,
    *children,
    label: str | Component | None = None,
    checked: Var[bool] | bool | None = None,
    default_checked: Var[bool] | bool | None = None,
    indeterminate: Var[bool] | bool | None = None,
    disabled: Var[bool] | bool | None = None,
    required: Var[bool] | bool | None = None,
    name: Var[str] | str | None = None,
    value: Var[str] | str | None = None,
    on_checked_change: EventType[()] | EventType[bool] | EventType[bool, dict] | None = None,
    **props
) -> HighLevelCheckbox

​
CheckboxRoot.create

@classmethod
def create(
    cls,
    *children,
    checked: Var[bool] | bool | None = None,
    default_checked: Var[bool] | bool | None = None,
    indeterminate: Var[bool] | bool | None = None,
    disabled: Var[bool] | bool | None = None,
    on_checked_change: EventType[()] | EventType[bool] | EventType[bool, dict] | None = None,
    **props
) -> CheckboxRoot

​
Return Types

  • HighLevelCheckbox - High-level checkbox with optional label
  • CheckboxRoot - Root checkbox component
  • CheckboxIndicator - Checkbox indicator (checkmark)

Build docs developers (and LLMs) love

Get started for freeTalk to us