Checkbox Options Plugin

The checkbox-options plugin renders a checkbox next to each option in the dropdown, providing a visual indicator of selected state. This is especially useful for multiple-select elements.

Usage

<select
  data-dot-select
  data-plugins="checkbox-options"
  multiple
  data-close-on-select="false"
  data-placeholder="Select items..."
>
  <option value="notifications">Email Notifications</option>
  <option value="newsletter">Weekly Newsletter</option>
  <option value="updates">Product Updates</option>
  <option value="marketing">Marketing Emails</option>
  <option value="security">Security Alerts</option>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-plugins="checkbox-options"
      multiple
      data-close-on-select="false"
      data-placeholder="Select items..."
    >
      <option value="notifications">Email Notifications</option>
      <option value="newsletter">Weekly Newsletter</option>
      <option value="updates">Product Updates</option>
      <option value="marketing">Marketing Emails</option>
      <option value="security">Security Alerts</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="checkbox-options"
    multiple
    data-close-on-select="false"
    data-placeholder="Select items..."
  >
    <option value="notifications">Email Notifications</option>
    <option value="newsletter">Weekly Newsletter</option>
    <option value="updates">Product Updates</option>
    <option value="marketing">Marketing Emails</option>
    <option value="security">Security Alerts</option>
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Behavior

• Each option in the dropdown displays a checkbox to its left (right in RTL mode)
• Selected options show a checked checkbox
• Clicking an option toggles the checkbox and the selection state
• Works with data-close-on-select="false" to keep the dropdown open for multiple selections

TIP

Set data-close-on-select="false" when using checkbox-options so users can select multiple items without the dropdown closing after each click.

With Optgroups

Checkboxes work alongside optgroups:

<select
  data-dot-select
  data-plugins="checkbox-options"
  multiple
  data-close-on-select="false"
  data-placeholder="Select permissions..."
>
  <optgroup label="Read">
    <option value="read-posts">Posts</option>
    <option value="read-users">Users</option>
    <option value="read-settings">Settings</option>
  </optgroup>
  <optgroup label="Write">
    <option value="write-posts">Posts</option>
    <option value="write-users">Users</option>
    <option value="write-settings">Settings</option>
  </optgroup>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-plugins="checkbox-options"
      multiple
      data-close-on-select="false"
      data-placeholder="Select permissions..."
    >
      <optgroup label="Read">
        <option value="read-posts">Posts</option>
        <option value="read-users">Users</option>
        <option value="read-settings">Settings</option>
      </optgroup>
      <optgroup label="Write">
        <option value="write-posts">Posts</option>
        <option value="write-users">Users</option>
        <option value="write-settings">Settings</option>
      </optgroup>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="checkbox-options"
    multiple
    data-close-on-select="false"
    data-placeholder="Select permissions..."
  >
    <optgroup label="Read">
      <option value="read-posts">Posts</option>
      <option value="read-users">Users</option>
      <option value="read-settings">Settings</option>
    </optgroup>
    <optgroup label="Write">
      <option value="write-posts">Posts</option>
      <option value="write-users">Users</option>
      <option value="write-settings">Settings</option>
    </optgroup>
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Styling

Customize the checkbox appearance:

.dot-select .ds-option-checkbox {
  width: 16px;
  height: 16px;
  border: 2px solid #cbd5e1;
  border-radius: 3px;
  margin-right: 8px;
  flex-shrink: 0;
}

.dot-select .ds-option-checkbox.checked {
  background-color: #3b82f6;
  border-color: #3b82f6;
}

Accessibility

Each checkbox is rendered with the appropriate role="checkbox" and aria-checked attributes for screen reader compatibility.