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 { reactive, ref, watch } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const parentChecked = ref<CheckedState>(false)
const childCheckedItems = reactive([false, false])

watch(childCheckedItems, (items) => {
  parentChecked.value = items.every(Boolean)
    ? true
    : items.indexOf(true) < 0
      ? false
      : 'indeterminate'
})

watch(parentChecked, (parentVal) => {
  if (parentVal === 'indeterminate') return
  childCheckedItems.map((_, idx) => {
    childCheckedItems[idx] = parentVal
  })
  return
})
</script>

<template>
  <Checkbox.Root defaultChecked>
    <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 CheckedState } from '@ark-ui/react'
import { useState } from 'react'

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

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

const Controlled = () => {
  const [checked, setChecked] = createSignal<CheckedState>(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 { reactive, ref, watch } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const parentChecked = ref<CheckedState>(false)
const childCheckedItems = reactive([false, false])

watch(childCheckedItems, (items) => {
  parentChecked.value = items.every(Boolean)
    ? true
    : items.indexOf(true) < 0
      ? false
      : 'indeterminate'
})

watch(parentChecked, (parentVal) => {
  if (parentVal === 'indeterminate') return
  childCheckedItems.map((_, idx) => {
    childCheckedItems[idx] = parentVal
  })
  return
})
</script>

<template>
  <Checkbox.Root v-model="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 { reactive, ref, watch } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const parentChecked = ref<CheckedState>(false)
const childCheckedItems = reactive([false, false])

watch(childCheckedItems, (items) => {
  parentChecked.value = items.every(Boolean)
    ? true
    : items.indexOf(true) < 0
      ? false
      : 'indeterminate'
})

watch(parentChecked, (parentVal) => {
  if (parentVal === 'indeterminate') return
  childCheckedItems.map((_, idx) => {
    childCheckedItems[idx] = parentVal
  })
  return
})
</script>

<template>
  <div style="padding-left: 20px; display: flex; flex-direction: column; gap: 4px">
    <Checkbox.Root v-model="parentChecked">
      <Checkbox.Control data-testid="parent-control">
        <span v-if="parentChecked === true">✓</span>
        <span v-else-if="parentChecked === 'indeterminate'">-</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="childCheckedItems[0]">
        <Checkbox.Control>
          <span v-if="childCheckedItems[0]">✓</span>
        </Checkbox.Control>
        <Checkbox.Label> Child One Checkbox</Checkbox.Label>
      </Checkbox.Root>
      <Checkbox.Root v-model="childCheckedItems[1]">
        <Checkbox.Control>
          <span v-if="childCheckedItems[1]">✓</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 { reactive, ref, watch } from 'vue'
import { Checkbox, type CheckedState } from '@ark-ui/vue'

const checked = ref<CheckedState>(false)
const parentChecked = ref<CheckedState>(false)
const childCheckedItems = reactive([false, false])

watch(childCheckedItems, (items) => {
  parentChecked.value = items.every(Boolean)
    ? true
    : items.indexOf(true) < 0
      ? false
      : 'indeterminate'
})

watch(parentChecked, (parentVal) => {
  if (parentVal === 'indeterminate') return
  childCheckedItems.map((_, idx) => {
    childCheckedItems[idx] = parentVal
  })
  return
})
</script>

<template>
  <Checkbox.Root v-slot="{ isChecked }">
    <Checkbox.Label>Checkbox</Checkbox.Label>
    <Checkbox.Control>
      <span v-if="isChecked">✓</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`