Dropdown Header Plugin

The dropdown-header plugin adds a customizable header section to the top of the dropdown panel. Use it for titles, instructions, or action links.

Usage

<select
  data-dot-select
  data-plugins="dropdown-header"
  data-plugin-dropdown-header-title="Select a Team Member"
  data-placeholder="Choose..."
>
  <option value="1">Alice Johnson</option>
  <option value="2">Bob Smith</option>
  <option value="3">Carol Williams</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="dropdown-header"
      data-plugin-dropdown-header-title="Select a Team Member"
      data-placeholder="Choose..."
    >
      <option value="1">Alice Johnson</option>
      <option value="2">Bob Smith</option>
      <option value="3">Carol Williams</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="dropdown-header"
    data-plugin-dropdown-header-title="Select a Team Member"
    data-placeholder="Choose..."
  >
    <option value="1">Alice Johnson</option>
    <option value="2">Bob Smith</option>
    <option value="3">Carol Williams</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>

Configuration

Attribute	Description	Default
data-plugin-dropdown-header-title	Title text displayed in the header	""
data-plugin-dropdown-header-html	Custom HTML content for the header	—
data-plugin-dropdown-header-class	Additional CSS class for the header element	""

Custom HTML Header

For more complex headers, use the HTML attribute:

<select
  data-dot-select
  data-plugins="dropdown-header"
  data-plugin-dropdown-header-html="<div class='custom-header'><strong>Users</strong><a href='/users/new'>+ Add New</a></div>"
  multiple
  data-placeholder="Select users..."
>
  <option value="1">Alice</option>
  <option value="2">Bob</option>
  <option value="3">Carol</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="dropdown-header"
      data-plugin-dropdown-header-html="<div class='custom-header'><strong>Users</strong><a href='/users/new'>+ Add New</a></div>"
      multiple
      data-placeholder="Select users..."
    >
      <option value="1">Alice</option>
      <option value="2">Bob</option>
      <option value="3">Carol</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="dropdown-header"
    data-plugin-dropdown-header-html="<div class='custom-header'><strong>Users</strong><a href='/users/new'>+ Add New</a></div>"
    multiple
    data-placeholder="Select users..."
  >
    <option value="1">Alice</option>
    <option value="2">Bob</option>
    <option value="3">Carol</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>

Styling

The header uses the .ds-dropdown-header CSS class:

.dot-select .ds-dropdown-header {
  padding: 8px 12px;
  border-bottom: 1px solid #e2e8f0;
  font-weight: 600;
  font-size: 0.8rem;
  color: #64748b;
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Example with Search

The header appears above the search input:

<select
  data-dot-select
  data-plugins="dropdown-header"
  data-plugin-dropdown-header-title="Assign to Project"
  data-searchable="true"
  data-placeholder="Search projects..."
>
  <option value="1">Project Alpha</option>
  <option value="2">Project Beta</option>
  <option value="3">Project Gamma</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="dropdown-header"
      data-plugin-dropdown-header-title="Assign to Project"
      data-searchable="true"
      data-placeholder="Search projects..."
    >
      <option value="1">Project Alpha</option>
      <option value="2">Project Beta</option>
      <option value="3">Project Gamma</option>
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="dropdown-header"
    data-plugin-dropdown-header-title="Assign to Project"
    data-searchable="true"
    data-placeholder="Search projects..."
  >
    <option value="1">Project Alpha</option>
    <option value="2">Project Beta</option>
    <option value="3">Project Gamma</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>