Checkbox
A control element that allows for multiple selections within a set.
Anatomy
To set up the checkbox correctly, you’ll need to understand its anatomy and how we name its parts.
Each part includes a
data-partattribute to help identify them in the DOM.
Design impact on the asChild property
The Checkbox.Root element of the checkbox is a label element. This is
because the checkbox is a form control and should be associated with a label to
provide context and meaning to the user. Otherwise, the HTML and accessibility
structure will be invalid.
If you need to use the
asChildproperty, make sure that thelabelelement is the direct child of theCheckbox.Rootcomponent.
Examples
Learn how to use the Checkbox component in your project. Let’s take a look at
the most basic example:
import { Checkbox } from '@ark-ui/react'
export const Basic = () => (
<Checkbox.Root defaultChecked>
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
import { Checkbox } from '@ark-ui/solid'
export const Basic = () => (
<Checkbox.Root>
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
<script setup lang="ts">
import { Checkbox } from '@ark-ui/vue'
</script>
<template>
<Checkbox.Root>
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
</template>
Controlled Checkbox
To create a controlled Checkbox component, manage the state of the checked
status using the checked prop and update it when the onCheckedChange event
handler is called:
import { useState } from 'react'
import { Checkbox } from '@ark-ui/react'
export const Controlled = () => {
const [checked, setChecked] = useState<Checkbox.CheckedState>(true)
return (
<Checkbox.Root checked={checked} onCheckedChange={(e) => setChecked(e.checked)}>
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
}
import { createSignal } from 'solid-js'
import { Checkbox } from '@ark-ui/solid'
export const Controlled = () => {
const [checked, setChecked] = createSignal<Checkbox.CheckedState>(true)
return (
<Checkbox.Root checked={checked()} onCheckedChange={(e) => setChecked(e.checked)}>
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
}
<script setup lang="ts">
import { ref } from 'vue'
import { Checkbox, type CheckboxCheckedState } from '@ark-ui/vue'
const checked = ref<CheckboxCheckedState>(false)
</script>
<template>
<Checkbox.Root v-model="checked">
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
</template>
Indeterminate Checkbox
In some cases, you may need a checkbox to represent a state that is neither
checked nor unchecked, known as the indeterminate state. This can be achieved by
setting the checked prop to indeterminate:
import { Checkbox } from '@ark-ui/react'
export const Indeterminate = () => (
<Checkbox.Root checked="indeterminate">
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
import { Checkbox } from '@ark-ui/solid'
export const Indeterminate = () => (
<Checkbox.Root checked="indeterminate">
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
)
<script setup lang="ts">
import { Checkbox } from '@ark-ui/vue'
</script>
<template>
<Checkbox.Root checked="indeterminate">
<Checkbox.Control />
<Checkbox.Label>Checkbox</Checkbox.Label>
</Checkbox.Root>
</template>
Render Prop Usage
For cases where you need more flexibility in rendering, the Checkbox component offers the use of a render prop. The render prop function gives you access to the checkbox’s API, allowing you to customize the checkbox control’s rendering:
Story not foundStory not foundStory not foundAPI Reference
Root
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean | |
checkedThe checked state of the checkbox | CheckedState | |
defaultCheckedThe initial checked state of the checkbox. | CheckedState | |
disabledWhether the checkbox is disabled | boolean | |
formThe id of the form that the checkbox belongs to. | string | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the checkbox. Useful for composition. | Partial<{
root: string
hiddenInput: string
control: string
label: string
}> | |
invalidWhether the checkbox is invalid | boolean | |
nameThe name of the input field in a checkbox.
Useful for form submission. | string | |
onCheckedChangeThe callback invoked when the checked state changes. | (details: CheckedChangeDetails) => void | |
readOnlyWhether the checkbox is read-only | boolean | |
requiredWhether the checkbox is required | boolean | |
valueThe value of checkbox input. Useful for form submission. | string | "on" |
Control
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Indicator
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Label
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |