Checkbox

An easily stylable checkbox component.

View as Markdown

Anatomy

Import the component and assemble its parts:

Anatomy

API reference

Root

Represents the checkbox itself. Renders a <button> element and a hidden <input> beside.

name

string

(default:

undefined

)
Name
Description

Identifies the field when a form is submitted.

Type

string

Default

undefined

defaultChecked

boolean

(default:

false

)
Description

Whether the checkbox is initially ticked.

To render a controlled checkbox, use the checked prop instead.

Type

boolean

Default

false

checked

boolean

(default:

undefined

)
Description

Whether the checkbox is currently ticked.

To render an uncontrolled checkbox, use the defaultChecked prop instead.

Type

boolean

Default

undefined

onCheckedChange

function

Description

Event handler called when the checkbox is ticked or unticked.

Type

((checked: boolean, event: Event) => void)

indeterminate

boolean

(default:

false

)
Description

Whether the checkbox is in a mixed state: neither ticked, nor unticked.

Type

boolean

Default

false

value

string

Name
Description

The value of the selected checkbox.

Type

string

nativeButton

boolean

(default:

true

)
Description

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).

Type

boolean

Default

true

parent

boolean

(default:

false

)
Name
Description

Whether the checkbox controls a group of child checkboxes.

Must be used in a Checkbox Group.

Type

boolean

Default

false

disabled

boolean

(default:

false

)
Description

Whether the component should ignore user interaction.

Type

boolean

Default

false

readOnly

boolean

(default:

false

)
Description

Whether the user should be unable to tick or untick the checkbox.

Type

boolean

Default

false

required

boolean

(default:

false

)
Description

Whether the user must tick the checkbox before submitting a form.

Type

boolean

Default

false

inputRef

Ref<HTMLInputElement>

Description

A ref to access the hidden <input> element.

Type

Ref<HTMLInputElement>

id

string

Name
Description

The id of the input element.

Type

string

className

string | function

Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type

| string
| ((state: Checkbox.Root.State) => string)

render

ReactElement | function

Name
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type

| ReactElement
| ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement)

data-checked

Present when the checkbox is checked.

data-unchecked

Present when the checkbox is not checked.

data-disabled

Present when the checkbox is disabled.

data-readonly

Present when the checkbox is readonly.

data-required

Present when the checkbox is required.

data-valid

Present when the checkbox is in valid state (when wrapped in Field.Root).

data-invalid

Present when the checkbox is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the checkbox's value has changed (when wrapped in Field.Root).

data-touched

Present when the checkbox has been touched (when wrapped in Field.Root).

data-filled

Present when the checkbox is checked (when wrapped in Field.Root).

data-focused

Present when the checkbox is focused (when wrapped in Field.Root).

Indicator

Indicates whether the checkbox is ticked. Renders a <span> element.

className

string | function

Description

CSS class applied to the element, or a function that returns a class based on the component’s state.

Type

| string
| ((state: Checkbox.Indicator.State) => string)

keepMounted

boolean

(default:

false

)
Description

Whether to keep the element in the DOM when the checkbox is not checked.

Type

boolean

Default

false

render

ReactElement | function

Name
Description

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.

Type

| ReactElement
| ((props: HTMLProps, state: Checkbox.Indicator.State) => ReactElement)

data-checked

Present when the checkbox is checked.

data-unchecked

Present when the checkbox is not checked.

data-disabled

Present when the checkbox is disabled.

data-readonly

Present when the checkbox is readonly.

data-required

Present when the checkbox is required.

data-valid

Present when the checkbox is in valid state (when wrapped in Field.Root).

data-invalid

Present when the checkbox is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the checkbox's value has changed (when wrapped in Field.Root).

data-touched

Present when the checkbox has been touched (when wrapped in Field.Root).

data-filled

Present when the checkbox is checked (when wrapped in Field.Root).

data-focused

Present when the checkbox is focused (when wrapped in Field.Root).

data-starting-style

Present when the checkbox indicator is animating in.

data-ending-style

Present when the checkbox indicator is animating out.

Examples

Form integration

To use a single checkbox in a form, pass the checkbox’s name to Field and use Field.Label to label the control.

Using Checkbox in a form