Basic Usage

DotSelect enhances native <select> elements. All configuration is done through HTML attributes — no JavaScript needed.

Single Select

Add data-dot-select to any <select> element:

<select data-dot-select placeholder="Choose a country..." data-allow-clear="true">
  <option value="us">United States</option>
  <option value="ca">Canada</option>
  <option value="uk">United Kingdom</option>
  <option value="de">Germany</option>
  <option value="fr">France</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 placeholder="Choose a country..." data-allow-clear="true">
      <option value="us">United States</option>
      <option value="ca">Canada</option>
      <option value="uk">United Kingdom</option>
      <option value="de">Germany</option>
      <option value="fr">France</option>
    </select>
  )
}

<template>
  <select data-dot-select placeholder="Choose a country..." data-allow-clear="true">
    <option value="us">United States</option>
    <option value="ca">Canada</option>
    <option value="uk">United Kingdom</option>
    <option value="de">Germany</option>
    <option value="fr">France</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>

Multiple Select

Add the native multiple attribute:

<select data-dot-select multiple placeholder="Select languages..." data-allow-clear="true">
  <option value="js">JavaScript</option>
  <option value="py">Python</option>
  <option value="rb">Ruby</option>
  <option value="go">Go</option>
  <option value="rs">Rust</option>
  <option value="java">Java</option>
  <option value="php">PHP</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 multiple placeholder="Select languages..." data-allow-clear="true">
      <option value="js">JavaScript</option>
      <option value="py">Python</option>
      <option value="rb">Ruby</option>
      <option value="go">Go</option>
      <option value="rs">Rust</option>
      <option value="java">Java</option>
      <option value="php">PHP</option>
    </select>
  )
}

<template>
  <select data-dot-select multiple placeholder="Select languages..." data-allow-clear="true">
    <option value="js">JavaScript</option>
    <option value="py">Python</option>
    <option value="rb">Ruby</option>
    <option value="go">Go</option>
    <option value="rs">Rust</option>
    <option value="java">Java</option>
    <option value="php">PHP</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>

Limiting Selections

Restrict the number of items with data-max-items:

<select data-dot-select multiple data-max-items="3" placeholder="Pick up to 3...">
  <option value="red">Red</option>
  <option value="blue">Blue</option>
  <option value="green">Green</option>
  <option value="yellow">Yellow</option>
  <option value="purple">Purple</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 multiple data-max-items="3" placeholder="Pick up to 3...">
      <option value="red">Red</option>
      <option value="blue">Blue</option>
      <option value="green">Green</option>
      <option value="yellow">Yellow</option>
      <option value="purple">Purple</option>
    </select>
  )
}

<template>
  <select data-dot-select multiple data-max-items="3" placeholder="Pick up to 3...">
    <option value="red">Red</option>
    <option value="blue">Blue</option>
    <option value="green">Green</option>
    <option value="yellow">Yellow</option>
    <option value="purple">Purple</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>

Optgroups

Native <optgroup> elements are fully supported:

<select data-dot-select placeholder="Choose a vehicle..." data-allow-clear="true">
  <optgroup label="Cars">
    <option value="sedan">Sedan</option>
    <option value="suv">SUV</option>
    <option value="coupe">Coupe</option>
  </optgroup>
  <optgroup label="Trucks">
    <option value="pickup">Pickup</option>
    <option value="semi">Semi</option>
  </optgroup>
  <optgroup label="Motorcycles">
    <option value="cruiser">Cruiser</option>
    <option value="sport">Sport Bike</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 placeholder="Choose a vehicle..." data-allow-clear="true">
      <optgroup label="Cars">
        <option value="sedan">Sedan</option>
        <option value="suv">SUV</option>
        <option value="coupe">Coupe</option>
      </optgroup>
      <optgroup label="Trucks">
        <option value="pickup">Pickup</option>
        <option value="semi">Semi</option>
      </optgroup>
      <optgroup label="Motorcycles">
        <option value="cruiser">Cruiser</option>
        <option value="sport">Sport Bike</option>
      </optgroup>
    </select>
  )
}

<template>
  <select data-dot-select placeholder="Choose a vehicle..." data-allow-clear="true">
    <optgroup label="Cars">
      <option value="sedan">Sedan</option>
      <option value="suv">SUV</option>
      <option value="coupe">Coupe</option>
    </optgroup>
    <optgroup label="Trucks">
      <option value="pickup">Pickup</option>
      <option value="semi">Semi</option>
    </optgroup>
    <optgroup label="Motorcycles">
      <option value="cruiser">Cruiser</option>
      <option value="sport">Sport Bike</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>

Pre-Selected Values

Use the native selected attribute:

<select data-dot-select multiple data-allow-clear="true">
  <option value="js" selected>JavaScript</option>
  <option value="py" selected>Python</option>
  <option value="rb">Ruby</option>
  <option value="go">Go</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 multiple data-allow-clear="true">
      <option value="js" selected>JavaScript</option>
      <option value="py" selected>Python</option>
      <option value="rb">Ruby</option>
      <option value="go">Go</option>
    </select>
  )
}

<template>
  <select data-dot-select multiple data-allow-clear="true">
    <option value="js" selected>JavaScript</option>
    <option value="py" selected>Python</option>
    <option value="rb">Ruby</option>
    <option value="go">Go</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>

Disabled

<select data-dot-select disabled placeholder="Cannot interact">
  <option value="1">Option 1</option>
  <option value="2" selected>Option 2</option>
  <option value="3">Option 3</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 disabled placeholder="Cannot interact">
      <option value="1">Option 1</option>
      <option value="2" selected>Option 2</option>
      <option value="3">Option 3</option>
    </select>
  )
}

<template>
  <select data-dot-select disabled placeholder="Cannot interact">
    <option value="1">Option 1</option>
    <option value="2" selected>Option 2</option>
    <option value="3">Option 3</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>

Allow Clear

Let users clear the selection with an × button:

<select data-dot-select data-allow-clear="true" placeholder="Optional field...">
  <option value="low">Low Priority</option>
  <option value="medium">Medium Priority</option>
  <option value="high">High Priority</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-allow-clear="true" placeholder="Optional field...">
      <option value="low">Low Priority</option>
      <option value="medium">Medium Priority</option>
      <option value="high">High Priority</option>
    </select>
  )
}

<template>
  <select data-dot-select data-allow-clear="true" placeholder="Optional field...">
    <option value="low">Low Priority</option>
    <option value="medium">Medium Priority</option>
    <option value="high">High Priority</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>

Sizes

Three sizes via data-size:

<div style="display:flex;flex-direction:column;gap:12px">
  <select data-dot-select data-size="sm" placeholder="Small...">
    <option value="a">Alpha</option>
    <option value="b">Beta</option>
  </select>
  <select data-dot-select placeholder="Default...">
    <option value="a">Alpha</option>
    <option value="b">Beta</option>
  </select>
  <select data-dot-select data-size="lg" placeholder="Large...">
    <option value="a">Alpha</option>
    <option value="b">Beta</option>
  </select>
</div>

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 (
    <div style="display:flex;flex-direction:column;gap:12px">
      <select data-dot-select data-size="sm" placeholder="Small...">
        <option value="a">Alpha</option>
        <option value="b">Beta</option>
      </select>
      <select data-dot-select placeholder="Default...">
        <option value="a">Alpha</option>
        <option value="b">Beta</option>
      </select>
      <select data-dot-select data-size="lg" placeholder="Large...">
        <option value="a">Alpha</option>
        <option value="b">Beta</option>
      </select>
    </div>
  )
}

<template>
  <div style="display:flex;flex-direction:column;gap:12px">
    <select data-dot-select data-size="sm" placeholder="Small...">
      <option value="a">Alpha</option>
      <option value="b">Beta</option>
    </select>
    <select data-dot-select placeholder="Default...">
      <option value="a">Alpha</option>
      <option value="b">Beta</option>
    </select>
    <select data-dot-select data-size="lg" placeholder="Large...">
      <option value="a">Alpha</option>
      <option value="b">Beta</option>
    </select>
  </div>
</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>

Combining Attributes

Attributes can be freely combined:

<select data-dot-select data-allow-clear="true" placeholder="Search team members..." data-size="lg">
  <option value="1">Alice Johnson</option>
  <option value="2">Bob Smith</option>
  <option value="3">Carol Williams</option>
  <option value="4">David Brown</option>
  <option value="5">Eve Davis</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-allow-clear="true" placeholder="Search team members..." data-size="lg">
      <option value="1">Alice Johnson</option>
      <option value="2">Bob Smith</option>
      <option value="3">Carol Williams</option>
      <option value="4">David Brown</option>
      <option value="5">Eve Davis</option>
    </select>
  )
}

<template>
  <select data-dot-select data-allow-clear="true" placeholder="Search team members..." data-size="lg">
    <option value="1">Alice Johnson</option>
    <option value="2">Bob Smith</option>
    <option value="3">Carol Williams</option>
    <option value="4">David Brown</option>
    <option value="5">Eve Davis</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>