Skip to content
Destyler UI Destyler UI Destyler UI
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,vue}
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/{checkbox,react}
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/{checkbox,svelte}
Terminal window 
      
        

          

            npm
             
            install
             
            @destyler/{checkbox,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, set the context’s checked property to true

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

Listening for changes

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

const [state, send] = useMachine(
  checkbox.machine({
    onCheckChange(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 checked state of the checkbox
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
string
The value of checkbox input. Useful for form submission.
dir
"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.

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

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

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

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

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

Composition

Combobox