Skip to main content

Checkbox

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

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

The builder store used to create the checkbox root.

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.