Checkbox

A control that allows the user to toggle between checked and not checked.

View code

Features

Supports indeterminate state
Full keyboard navigation
Can be controlled or uncontrolled

Anatomy

Root: The root container for the checkbox
Input: The native html input element that is hidden from view

Usage

To create a checkbox, use the createCheckbox builder function. Follow the anatomy or the example above to create your checkbox.

Indeterminate state

To create an indeterminate checkbox, set the checked argument as indeterminate.

    <script lang="ts">
  import { createCheckbox } from '@melt-ui/svelte'
 
  const { root, input, isChecked, isIndeterminate, checked } = createCheckbox({
    checked: 'indeterminate'
  })
  // or
  checked.set('indeterminate')
</script>

Disabling the checkbox

To disable the checkbox, set the disabled argument as true.

    <script lang="ts">
  import { createCheckbox } from '@melt-ui/svelte'
 
  const { root, input, isChecked, isIndeterminate, checked, options } = createCheckbox({
    disabled: true
  })
  // or
  options.update((prev) => ({ ...prev, disabled: true }))
</script>

Controlled access

To programatically control the checkbox, you can directly set the checked store. You can also update the options store with new arguments.

    <script lang="ts">
  import { createCheckbox } from '@melt-ui/svelte'
 
  export let checked: boolean | 'indeterminate' = true
  export let disabled = false
 
  const { checked: checkedStore, options } = createCheckbox({
    disabled,
    checked
  })
 
  $: checkedStore.set(checked)
  checkedStore.subscribe((v) => (checked = v))
  $: options.update((o) => ({ ...o, disabled }))
</script>

API Reference

createCheckbox

Props

Prop	Default	Type / Description
`checked`	`false`	`boolean \| 'indeterminate'` The initial checked state of the checkbox. `'indeterminate'` is used to indicate that the checkbox is in an indeterminate state.
`disabled`	`false`	`boolean` Whether or not the checkbox is disabled.
`required`	`false`	`boolean` Whether or not the checkbox is required.
`name`	-	`string` The name of the checkbox.
`value`	-	`string` The value of the checkbox.

Returned Props

Returned Prop	Type	Description
`isChecked`	`Readable<boolean>`	A derived store that returns whether or not the checkbox is checked.
`isIndeterminate`	`Readable<boolean>`	A derived store that returns whether or not the checkbox is in an indeterminate state.
`root`	-	The builder store used to create the checkbox root.
`input`	-	The builder store used to create the checkbox input.

root

Data Attributes

Data Attribute	Value
`[data-disabled]`	Present when the element is disabled.
`[data-state]`	`'checked' \| 'unchecked' \| 'indeterminate'`
`[data-melt-checkbox]`	Present on all checkbox elements.

input

Data Attributes

Data Attribute	Value
`[data-melt-checkbox-input]`	Present on all checkbox input elements.

Accessibility

Adheres to the tri-state Checkbox WAI-ARIA design pattern

Key	Behavior
`Space`	Toggles the checkbox state.

On This Page