Installation

DotSelect can be installed via npm, loaded from a CDN, or imported as an ES module.

npm

npm install dot-select

Then import it in your project:

import DotSelect from 'dot-select';
import 'dot-select/dist/css/dot-select.min.css';

TIP

If you are using a bundler like Vite, Webpack, or Rollup, the CSS import will be handled automatically.

CDN (jsDelivr)

Add the stylesheet and script to your HTML:

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dot-select@latest/dist/css/dot-select.min.css">

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/dot-select@latest/dist/dot-select.min.js"></script>

For production, pin to a specific version:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dot-select@1.0.7/dist/css/dot-select.min.css">
<script src="https://cdn.jsdelivr.net/npm/dot-select@1.0.7/dist/dot-select.min.js"></script>

With a Theme

To use a specific theme, replace the default CSS with the theme CSS:

<!-- Bootstrap 5 theme -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dot-select@latest/dist/css/themes/bootstrap5.min.css">

<!-- Tailwind theme -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/dot-select@latest/dist/css/themes/tailwind.min.css">

ES Module Import

For modern browsers that support ES modules:

<script type="module">
  import DotSelect from 'https://cdn.jsdelivr.net/npm/dot-select@latest/dist/esm/dot-select.min.mjs';

  // DotSelect auto-initializes elements with data-dot-select
  // Or manually initialize:
  DotSelect.init();
</script>

Manual Initialization

By default, DotSelect auto-initializes all <select data-dot-select> elements when the DOM is ready. You can disable this and initialize manually:

<script src="https://cdn.jsdelivr.net/npm/dot-select@latest/dist/dot-select.min.js"
        data-dot-select-auto-init="false"></script>

<script>
  // Initialize all dot-select elements
  DotSelect.init();

  // Or initialize a specific element
  const select = document.querySelector('#my-select');
  const instance = new DotSelect(select);
</script>

Including Plugins

Plugins are included in the main bundle. Activate them via the data-plugins attribute:

<select data-dot-select data-plugins="remove-button,clear-button">
  <option value="1">Option 1</option>
  <option value="2">Option 2</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="remove-button,clear-button">
      <option value="1">Option 1</option>
      <option value="2">Option 2</option>
    </select>
  )
}

<template>
  <select data-dot-select data-plugins="remove-button,clear-button">
    <option value="1">Option 1</option>
    <option value="2">Option 2</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>

Or register custom plugins via JavaScript:

import DotSelect from 'dot-select';
import { myPlugin } from './my-plugin';

DotSelect.plugin('my-plugin', myPlugin);

Including Locales

Locales are bundled with DotSelect. Set the language via the data-locale attribute:

<select data-dot-select data-locale="fr">
  <option value="1">Option Un</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-locale="fr">
      <option value="1">Option Un</option>
    </select>
  )
}

<template>
  <select data-dot-select data-locale="fr">
    <option value="1">Option Un</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>

Or register a custom locale:

DotSelect.registerLocale('custom', {
  noResults: 'Nothing found',
  searching: 'Looking...',
  loadMore: 'Show more results',
  addItem: 'Add "{@term}"',
});

Verifying Installation

After installation, open your browser console and check:

console.log(DotSelect.version); // e.g., "1.0.0"

Or verify that a select element has been initialized:

const instance = DotSelect.getInstance(document.querySelector('#my-select'));
console.log(instance); // DotSelect instance or null

WARNING

Make sure the CSS file is loaded before the JavaScript file to prevent a flash of unstyled content (FOUC).