Plugins

DotSelect has a modular plugin system that lets you extend functionality without bloating the core library. Plugins are activated via the data-plugins attribute.

Activating Plugins

Add plugin names as a comma-separated list:

<select data-dot-select data-plugins="remove-button,clear-button" multiple>
  <option value="1">Option 1</option>
  <option value="2">Option 2</option>
</select>

Built-in Plugins

Plugin	Description
remove-button	Adds an "x" button to each selected item for easy removal
clear-button	Adds a button to clear all selected items at once
tags	Enables comma-separated input and paste support for tagging
checkbox-options	Renders checkboxes next to each option in the dropdown
dropdown-header	Adds a customizable header to the dropdown panel
virtual-scroll	Renders only visible options for large lists (10,000+ items)
drag-drop	Allows reordering selected items via drag and drop

Creating Custom Plugins

Register a custom plugin using DotSelect.plugin():

DotSelect.plugin('my-plugin', (instance, options) => {
  return {
    init() {
      // Called when DotSelect initializes
      console.log('Plugin initialized on', instance.getElement().id);
    },

    destroy() {
      // Called when DotSelect is destroyed
      // Clean up event listeners, DOM elements, etc.
    },

    onOpen() {
      // Called when the dropdown opens
    },

    onClose() {
      // Called when the dropdown closes
    },

    onSearch(term) {
      // Called when the user types in the search box
      // Return false to prevent default search behavior
    },

    onChange(value, data) {
      // Called when the value changes
    },

    onRender(wrapper) {
      // Called after the component renders
      // Use this to modify the wrapper DOM
    },

    onOptionRender(optionEl, data) {
      // Called for each option element as it renders
      // Modify the option DOM or return a new element
    },

    onItemRender(itemEl, data) {
      // Called for each selected item element as it renders
      // Modify the item DOM or return a new element
    },
  };
});

Then use it in HTML:

<select data-dot-select data-plugins="my-plugin">
  <option value="1">Option 1</option>
</select>

Plugin Hooks

All hooks are optional. Implement only the ones you need.

Hook	Arguments	Description
init()	—	Called once during DotSelect initialization
destroy()	—	Called when the instance is destroyed; clean up here
onOpen()	—	Dropdown has opened
onClose()	—	Dropdown has closed
onSearch(term)	term: string	User typed in search. Return false to cancel default search
onChange(value, data)	value: string|string[], data: object|object[]	Selection changed
onRender(wrapper)	wrapper: HTMLElement	Component has rendered
onOptionRender(el, data)	el: HTMLElement, data: object	An option element is rendering
onItemRender(el, data)	el: HTMLElement, data: object	A selected item element is rendering

Plugin Options

Pass options to plugins using data-plugin-{name}-{option} attributes:

<select
  data-dot-select
  data-plugins="dropdown-header"
  data-plugin-dropdown-header-title="Select a User"
>
  <option value="1">Alice</option>
  <option value="2">Bob</option>
</select>

Example: Highlight Plugin

A complete example of a custom plugin that highlights the most recently selected item:

DotSelect.plugin('highlight-last', (instance) => {
  let lastItem = null;

  return {
    onChange(value, data) {
      // Remove highlight from previous item
      if (lastItem) {
        lastItem.classList.remove('ds-highlight-last');
      }

      // Highlight the newest item
      const items = instance.getWrapper().querySelectorAll('.ds-item');
      if (items.length > 0) {
        lastItem = items[items.length - 1];
        lastItem.classList.add('ds-highlight-last');
      }
    },

    destroy() {
      lastItem = null;
    },
  };
});

.ds-highlight-last {
  animation: highlight-pulse 0.5s ease;
}

@keyframes highlight-pulse {
  0% { background-color: #fef08a; }
  100% { background-color: transparent; }
}

TIP

Plugins have full access to the DotSelect instance via the first argument of the factory function. Use instance.getElement(), instance.getWrapper(), and all other instance methods.