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>

    <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>

    <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>

API Reference

createCheckbox

The builder function used to create the checkbox component.

Props

Prop	Default	Type / Description
`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. Submitted with its owning form as part of a name/value pair.
`value`	-	`string` The value given as data when submitted with a `name`.
`defaultChecked`	`false`	`boolean \| 'indeterminate'` The default checked state of the checkbox. `'indeterminate'` is used to indicate that the checkbox is in an indeterminate state.
`checked`	-	`Writable<boolean \| 'indeterminate'>` The controlled checked state store of the checkbox. If provided, this will override the value passed to `defaultChecked`. See Bring Your Own Store
`onCheckedChange`	-	`ChangeFn<boolean \| 'indeterminate'>` A callback called when the value of the `checked` store should be changed. This is useful for controlling the checked state of the checkbox from outside the checkbox. See Change Functions

Elements

Element	Description
`root`	The builder store used to create the checkbox root.
`input`	The builder store used to create the checkbox input.

States

State	Description
`checked`	A writable store that contains the checked state of the checkbox.

Helpers

Helper	Description
`isChecked`	A derived store that returns whether or not the checkbox is checked.
`isIndeterminate`	A derived store that returns whether or not the checkbox is in an indeterminate state.

Options

Option	Description
`disabled`	Whether or not the checkbox is disabled.
`required`	Whether or not the checkbox is required.
`name`	The name of the checkbox. Submitted with its owning form as part of a name/value pair.
`value`	The value given as data when submitted with a `name`.

root

The checkbox element.

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.

Custom Events

Event	Value
`m-keydown`	`(e: ) => void`
`m-click`	`(e: ) => void`

input

The native input element.

Data Attributes

Data Attribute	Value
`[data-melt-checkbox-hidden-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