Checkbox

The Checkbox component provides a binary choice interface that allows users to select or deselect options. It’s ideal for forms, settings, and any scenario where users need to make yes/no or on/off decisions.

Usage Guidelines

Basic Checkbox

Use the Checkbox component for binary choices in forms and settings.

<Checkbox>I agree to the terms and conditions</Checkbox>

Checked State

Use the defaultSelected prop to set the initial state of the checkbox (uncontrolled), or use isSelected with onChange for controlled state.

<Checkbox defaultSelected>Subscribe to newsletter</Checkbox>

Controlled State

For controlled state, use isSelected with onChange to manage the checkbox state externally.

const [checked, setChecked] = useState(false);

<Checkbox isSelected={checked} onChange={setChecked}>
  Controlled checkbox
</Checkbox>;

Disabled State

Use the isDisabled prop to prevent user interaction with the checkbox.

<Checkbox isDisabled>This option is not available</Checkbox>

Indeterminate State

Use the isIndeterminate prop to show a partially selected state, often used for parent checkboxes that control multiple child checkboxes.

<Checkbox isIndeterminate>Select all items</Checkbox>

Without Label

You can use the Checkbox without a visible label for custom layouts.

<Checkbox />

Props

interface CheckboxProps

className ? string

The CSS className for the element. A function may be provided to compute the class based on component state.

validationBehavior ? "native" | "aria"

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to 'native'

isIndeterminate ? boolean

Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction.

value ? string

The value of the input element, used when submitting an HTML form. See MDN.

defaultSelected ? boolean

Whether the element should be selected (uncontrolled).

isSelected ? boolean

Whether the element should be selected (controlled).

onChange ? (isSelected: boolean) => void

Handler that is called when the element's selection state changes.

isDisabled ? boolean

Whether the input is disabled.

isReadOnly ? boolean

Whether the input can be selected but not changed by the user.

isRequired ? boolean

Whether user input is required on the input before form submission.

isInvalid ? boolean

Whether the input value is invalid.

validate ? (value: boolean) => true | ValidationError | null

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

autoFocus ? boolean

Whether the element should receive focus on render.

onFocus ? (e: FocusEvent) => void

Handler that is called when the element receives focus.

onBlur ? (e: FocusEvent) => void

Handler that is called when the element loses focus.

onFocusChange ? (isFocused: boolean) => void

Handler that is called when the element's focus status changes.

onKeyDown ? (e: KeyboardEvent) => void

Handler that is called when a key is pressed.

onKeyUp ? (e: KeyboardEvent) => void

Handler that is called when a key is released.

name ? string

The name of the input element, used when submitting an HTML form. See MDN.

form ? string

The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.

excludeFromTabOrder ? boolean

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

id ? string

The element's unique identifier. See MDN.

onPress ? (e: PressEvent) => void

Handler that is called when the press is released over the target.

onPressStart ? (e: PressEvent) => void

Handler that is called when a press interaction starts.

onPressEnd ? (e: PressEvent) => void

Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.

onPressChange ? (isPressed: boolean) => void

Handler that is called when the press state changes.

onPressUp ? (e: PressEvent) => void

Handler that is called when a press is released over the target, regardless of whether it started on the target or not.

onClick ? (e: MouseEvent) => void

Not recommended – use onPress instead. onClick is an alias for onPress provided for compatibility with other libraries. onPress provides additional event details for non-mouse interactions.

inputRef ? RefObject | null>

A ref for the HTML input element.

onHoverStart ? (e: HoverEvent) => void

Handler that is called when a hover interaction starts.

onHoverEnd ? (e: HoverEvent) => void

Handler that is called when a hover interaction ends.

onHoverChange ? (isHovering: boolean) => void

Handler that is called when the hover state changes.

style ? StyleOrFunction

The inline style for the element. A function may be provided to compute the style based on component state.

slot ? string | null

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.