Checkbox | Ark UI

Label

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-part attribute to help identify them in the DOM.

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'

const Basic = () => (
  <Checkbox.Root defaultChecked>
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
    <Checkbox.Indicator>Indicator</Checkbox.Indicator>
  </Checkbox.Root>
)

import { Checkbox } from '@ark-ui/solid'

const Basic = () => (
  <Checkbox.Root>
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
    <Checkbox.Indicator>Indicator</Checkbox.Indicator>
  </Checkbox.Root>
)

<script setup lang="ts">
import { computed, ref } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const childCheckedItems = ref([false, false])
const parentChecked = computed({
  get() {
    return childCheckedItems.value.every(Boolean)
      ? true
      : childCheckedItems.value.some(Boolean)
        ? 'indeterminate'
        : false
  },
  set(val: CheckedState) {
    if (val === 'indeterminate') return
    childCheckedItems.value = childCheckedItems.value.map(() => val)
  },
})
</script>

<template>
  <Checkbox.Root default-checked>
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
  </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 { Checkbox, type CheckboxState } from '@ark-ui/react'
import { useState } from 'react'

const Controlled = () => {
  const [checked, setChecked] = useState<CheckboxState>(true)
  return (
    <Checkbox.Root checked={checked} onCheckedChange={(e) => setChecked(e.checked)}>
      <Checkbox.Label>Checkbox</Checkbox.Label>
      <Checkbox.Control />
    </Checkbox.Root>
  )
}

import { Checkbox, type CheckboxState } from '@ark-ui/solid'
import { createSignal } from 'solid-js'

const Controlled = () => {
  const [checked, setChecked] = createSignal<CheckboxState>(true)
  return (
    <Checkbox.Root checked={checked()} onCheckedChange={(e) => setChecked(e.checked)}>
      <Checkbox.Label>Checkbox</Checkbox.Label>
      <Checkbox.Control />
    </Checkbox.Root>
  )
}

<script setup lang="ts">
import { computed, ref } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const childCheckedItems = ref([false, false])
const parentChecked = computed({
  get() {
    return childCheckedItems.value.every(Boolean)
      ? true
      : childCheckedItems.value.some(Boolean)
        ? 'indeterminate'
        : false
  },
  set(val: CheckedState) {
    if (val === 'indeterminate') return
    childCheckedItems.value = childCheckedItems.value.map(() => val)
  },
})
</script>

<template>
  <Checkbox.Root v-model:checked="checked">
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
  </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'

const Indeterminate = () => (
  <Checkbox.Root checked="indeterminate">
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
  </Checkbox.Root>
)

import { Checkbox } from '@ark-ui/solid'

const Indeterminate = () => (
  <Checkbox.Root checked="indeterminate">
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control />
  </Checkbox.Root>
)

<script setup lang="ts">
import { computed, ref } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const childCheckedItems = ref([false, false])
const parentChecked = computed({
  get() {
    return childCheckedItems.value.every(Boolean)
      ? true
      : childCheckedItems.value.some(Boolean)
        ? 'indeterminate'
        : false
  },
  set(val: CheckedState) {
    if (val === 'indeterminate') return
    childCheckedItems.value = childCheckedItems.value.map(() => val)
  },
})
</script>

<template>
  <div style="padding-left: 20px; display: flex; flex-direction: column; gap: 4px">
    <Checkbox.Root v-model:checked="parentChecked" v-slot="{ isChecked, isIndeterminate }">
      <Checkbox.Control>
        <span v-if="isChecked">✓</span>
        <span v-if="isIndeterminate">-</span>
      </Checkbox.Control>
      <Checkbox.Label> Parent Checkbox</Checkbox.Label>
    </Checkbox.Root>
    <div style="padding-left: 20px; display: flex; flex-direction: column; gap: 4px">
      <Checkbox.Root v-model:checked="childCheckedItems[0]" v-slot="{ isChecked }">
        <Checkbox.Control>
          <span v-if="isChecked">✓</span>
        </Checkbox.Control>
        <Checkbox.Label> Child One Checkbox</Checkbox.Label>
      </Checkbox.Root>
      <Checkbox.Root v-model:checked="childCheckedItems[1]" v-slot="{ isChecked }">
        <Checkbox.Control>
          <span v-if="isChecked">✓</span>
        </Checkbox.Control>
        <Checkbox.Label>Child Two Checkbox</Checkbox.Label>
      </Checkbox.Root>
    </div>
  </div>
</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:

import { Checkbox } from '@ark-ui/react'

const RenderProp = () => (
  <Checkbox.Root>
    {(api) => (
      <>
        <Checkbox.Label>Checkbox</Checkbox.Label>
        <Checkbox.Control>
          {api.isChecked && <span>✓</span>}
          {api.isIndeterminate && <span>-</span>}
        </Checkbox.Control>
      </>
    )}
  </Checkbox.Root>
)

import { Checkbox } from '@ark-ui/solid'

const RenderProp = () => (
  <Checkbox.Root>
    {(api) => (
      <>
        <Checkbox.Label>Checkbox</Checkbox.Label>
        <Checkbox.Control>
          {api().isChecked && <span>✓</span>}
          {api().isIndeterminate && <span>-</span>}
        </Checkbox.Control>
      </>
    )}
  </Checkbox.Root>
)

<script setup lang="ts">
import { computed, ref } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const childCheckedItems = ref([false, false])
const parentChecked = computed({
  get() {
    return childCheckedItems.value.every(Boolean)
      ? true
      : childCheckedItems.value.some(Boolean)
        ? 'indeterminate'
        : false
  },
  set(val: CheckedState) {
    if (val === 'indeterminate') return
    childCheckedItems.value = childCheckedItems.value.map(() => val)
  },
})
</script>

<template>
  <Checkbox.Root v-slot="{ isChecked, isIndeterminate }">
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control>
      <span v-if="isChecked">✓</span>
      <span v-if="isIndeterminate">-</span>
    </Checkbox.Control>
  </Checkbox.Root>
</template>

API Reference

Root

Prop	Type	Default
`asChild`	`boolean`
`checked`	`CheckedState`
`defaultChecked`	`CheckedState`
`dir`	`'ltr' \| 'rtl'`	`"ltr"`
`disabled`	`boolean`
`form`	`string`
`getRootNode`	`() => Node \| ShadowRoot \| Document`
`id`	`string`
`ids`	`Partial<{ root: string hiddenInput: string control: string label: string }>`
`invalid`	`boolean`
`name`	`string`
`onCheckedChange`	`(details: CheckedChangeDetails) => void`
`required`	`boolean`
`value`	`string`	`"on"`

Label

Prop	Type	Default
`asChild`	`boolean`

Control

Prop	Type	Default
`asChild`	`boolean`

Indicator

Prop	Type	Default
`asChild`	`boolean`