Skip to content
Destyler Destyler Destyler
Docs
Checkbox

Checkbox

A checkbox allows users to make a binary choice, i.e. a choice between one of two possible mutually exclusive options.

Features

Install

Install the component from your command line.

Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/checkbox @destyler/vue
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/checkbox @destyler/react
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/checkbox @destyler/svelte
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/checkbox @destyler/solid

Anatomy

Import all parts and piece them together.

<script setup lang="ts">
import * as checkbox from '@destyler/checkbox'
import { normalizeProps, useMachine } from '@destyler/vue'
import { computed, useId } from 'vue'


const [state, send] = useMachine(checkbox.machine({ id: useId() }))


const api = computed(() =>
  checkbox.connect(state.value, send, normalizeProps),
)
</script>


<template>
  <label v-bind="api.getRootProps()">
    <div v-bind="api.getControlProps()" />
    <span v-bind="api.getLabelProps()" />
    <input v-bind="api.getHiddenInputProps()">
  </label>
</template>
import * as checkbox from '@destyler/checkbox'
import { normalizeProps, useMachine } from '@destyler/react'
import { useId } from 'react'


export default function Checkbox() {
  const [state, send] = useMachine(checkbox.machine({ id: useId() }))
  const api = checkbox.connect(state, send, normalizeProps)


  return (
    <label {...api.getRootProps()}>
      <div {...api.getControlProps()} />
      <span {...api.getLabelProps()} />
      <input {...api.getHiddenInputProps()} />
    </label>
  )
}
<script lang="ts">
  import * as checkbox from '@destyler/checkbox'
  import { normalizeProps, useMachine } from '@destyler/svelte'


  const id = $props.id()


  const [state, send] = useMachine(checkbox.machine({ id }))


  const api = $derived(checkbox.connect(state, send, normalizeProps))
</script>


<label {...api.getRootProps()}>
  <div {...api.getControlProps()}></div>
  <span {...api.getLabelProps()}></span>
  <input {...api.getHiddenInputProps()}>
</label>
import * as checkbox from '@destyler/checkbox'
import { normalizeProps, useMachine } from '@destyler/solid'
import { createMemo, createUniqueId } from 'solid-js'


export default function Checkbox() {
  const [state, send] = useMachine(checkbox.machine({
    name: 'checkbox',
    id: createUniqueId(),
  }))
  const api = createMemo(() => checkbox.connect(state, send, normalizeProps))


  return (
    <label {...api().getRootProps()}>
      <div {...api().getControlProps()} ></div>
      <span {...api().getLabelProps()}></span>
      <input {...api().getHiddenInputProps()} />
    </label>
  )
}

Indeterminate checkboxes

To make a checkbox indeterminate, set the context’s indeterminate property to true

const [state, send] = useMachine(
  checkbox.machine({
    indeterminate: true,
  }),
)

Disabling the checkbox

To make a checkbox disabled, set the context’s disabled property to true

const [state, send] = useMachine(
  checkbox.machine({
    disabled: true,
  }),
)

Making the checked by default

To make a checkbox checked by default without taking ownership of state, use defaultChecked. Prefer this over seeding with checked (which is presence-controlled after Phase 2).

const [state, send] = useMachine(
  checkbox.machine({
    defaultChecked: true,
  }),
)

Controlled usage

To control the checked state from your app, pass checked into machine(...) and sync with onCheckedChange (plus the adapter context option). Use defaultChecked for uncontrolled demos instead of always passing checked. See Controllable State.

const checked = false // your reactive state
checkbox.machine({
  id: "1",
  checked,
  onCheckedChange(details) {
    // details => { checked: boolean | "indeterminate" }
  },
})

Listening for changes

When the checkbox value changes, the onCheckedChange callback is invoked.

const [state, send] = useMachine(
  checkbox.machine({
    onCheckedChange(details) {
      // details => { checked: boolean }
      console.log("checkbox is:", details.checked)
    },
  }),
)

Usage within forms

To use checkbox within forms, use the exposed hiddenInputProps from the connect function and ensure you pass name value to the Destyler’s context. It will render a hidden input and ensure the value changes get propagated to the form correctly.

const [state, send] = useMachine(
  checkbox.machine({
    name: "fruits",
  }),
)

Styling Guide

Earlier, we mentioned that each checkbox part has a data-part attribute added to them to select and style them in the DOM.

Checked state

When the checkbox input is checked, the data-checked attribute is added to the root, control and label parts.

[data-part="root"][data-state="checked"] {
  /* styles for when checkbox is checked */
}


[data-part="control"][data-state="checked"] {
  /* styles for when checkbox is checked */
}


[data-part="label"][data-state="checked"] {
  /* styles for when checkbox is checked */
}

Focused state

When the checkbox input is focused, the data-focus attribute is added to the root, control and label parts.

[data-part="root"][data-focus] {
  /* styles for root focus state */
}


[data-part="control"][data-focus] {
  /* styles for control focus state */
}


[data-part="label"][data-focus] {
  /* styles for label focus state */
}

Disabled state

When the checkbox is disabled, the data-disabled attribute is added to the root, control and label parts.

[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}


[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}


[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}

Invalid state

When the checkbox is invalid, the data-invalid attribute is added to the root, control and label parts.

[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}


[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}


[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}

Methods and Properties

Machine Context

The checkbox machine exposes the following context properties:

ids
Partial<{ root: string; hiddenInput: string; control: string; label: string; }>
The ids of the elements in the checkbox. Useful for composition.
disabled
boolean
Whether the checkbox is disabled
invalid
boolean
Whether the checkbox is invalid
required
boolean
Whether the checkbox is required
checked
CheckedState
The controlled checked state of the checkbox
defaultChecked
CheckedState
The initial checked state of the checkbox when it is not controlled. Prefer this over seeding with `checked` for uncontrolled usage.
readOnly
boolean
Whether the checkbox is read-only
onCheckedChange
(details: CheckedChangeDetails) => void
The callback invoked when the checked state changes.
name
string
The name of the input field in a checkbox. Useful for form submission.
form
string
The id of the form that the checkbox belongs to.
value(default: "on")
string
The value of checkbox input. Useful for form submission.
dir(default: "ltr")
"ltr" | "rtl"
The document's text/writing direction.
id
string
The unique identifier of the machine.
getRootNode
() => ShadowRoot | Node | Document
A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The checkbox api exposes the following methods:

checked
boolean
Whether the checkbox is checked
disabled
boolean
Whether the checkbox is disabled
indeterminate
boolean
Whether the checkbox is indeterminate
focused
boolean
Whether the checkbox is focused
checkedState
CheckedState
The checked state of the checkbox
setChecked
(checked: CheckedState) => void
Function to set the checked state of the checkbox
toggleChecked
() => void
Function to toggle the checked state of the checkbox

Data Attributes

Root

attribute
description
data-active
Present when active or pressed
data-focus
Present when focused
data-focus-visible
Present when focused with keyboard
data-readonly
Present when read-only
data-hover
Present when hovered
data-disabled
Present when disabled
data-state
"indeterminate" | "checked" | "unchecked"
data-invalid
Present when invalid

Label

attribute
description
data-active
Present when active or pressed
data-focus
Present when focused
data-focus-visible
Present when focused with keyboard
data-readonly
Present when read-only
data-hover
Present when hovered
data-disabled
Present when disabled
data-state
"indeterminate" | "checked" | "unchecked"
data-invalid
Present when invalid

Control

attribute
description
data-active
Present when active or pressed
data-focus
Present when focused
data-focus-visible
Present when focused with keyboard
data-readonly
Present when read-only
data-hover
Present when hovered
data-disabled
Present when disabled
data-state
"indeterminate" | "checked" | "unchecked"
data-invalid
Present when invalid

Indicator

attribute
description
data-active
Present when active or pressed
data-focus
Present when focused
data-focus-visible
Present when focused with keyboard
data-readonly
Present when read-only
data-hover
Present when hovered
data-disabled
Present when disabled
data-state
"indeterminate" | "checked" | "unchecked"
data-invalid
Present when invalid

Accessibility

Keyboard Interaction

name
desc
Space
Toggle the checkbox

Controllable State

Combobox