Tagging & Searchable Dropdown with Multi-Select – Searchdown.js

Searchdown is a searchable dropdown component that adds search-as-you-type filtering, tag-based multi-select, and custom value entry to any HTML input element.

Features:

• Supports single and multi-select modes with tag-style display of chosen items.
• Filters dropdown options in real time as the user types into the search field.
• Accepts user-typed custom values and saves them optionally to the option list.
• Hides already-selected options from the dropdown list on demand.
• Sorts displayed options alphabetically in ascending or descending order.
• Limits the total number of visible options and the maximum number of allowed selections independently.
• Detects and blocks duplicate selections.
• Supports case-sensitive and case-insensitive search modes.
• Repositions the dropdown above the trigger field automatically when viewport space below is insufficient.
• Full theme control through CSS custom properties.
• Fires a callback on every selection change for reactive UI updates.
• Auto-initializes from HTML data attributes.
• Accepts a custom notification handler to replace the default browser alert globally.

Use Cases:

• Build a country selection form with hundreds of options.
• Create a blog post tagging system for content management dashboards.
• Develop a user assignment tool for project management software.
• Implement an e-commerce product filter interface.

How to use it:

1. Install Searchdown and import the default export and any named utilities you need:

# NPM
$ npm install searchdown

// Import the default export and any named utilities you need
import searchdown, { getValue, setValue } from 'dist/searchdown';
import 'searchdown/styles'; // Load the default CSS

2. Or load directly in the browser via CDN:

<!-- Default stylesheet -->
<link rel="stylesheet" href="https://unpkg.com/searchdown/dist/searchdown.css">
<!-- UMD bundle -->
<script src="https://unpkg.com/searchdown/dist/searchdown.umd.js"></script>

3. Initialize Searchdown on a target element by ID.

searchdown('#language-picker', {
  values: ['JavaScript', 'TypeScript', 'Python', 'Rust', 'Go'],
  placeholder: 'Pick a language...',
  multiple: true,
  initialValues: ['JavaScript']
  // more options here
});

// UMD (Browser Script)
  Searchdown.searchdown('#language-picker', {
  values: ['JavaScript', 'TypeScript', 'Python', 'Rust', 'Go'],
  placeholder: 'Pick a language...',
  multiple: true,
  initialValues: ['JavaScript']
  // more options here
});

4. Enable auto-initialization via Data Attributes. Mark any element with class="searchdown" and prefix each option with data-sd_. Call enableAutoCreate() once and the library scans the DOM itself.

<div class="searchdown"
  data-sd_values='["React", "Vue", "Angular", "Svelte"]'
  data-sd_multiple="true"
  data-sd_placeholder="Select frameworks...">
</div>

<script type="module">
  import { enableAutoCreate } from 'dist/searchdown';
  // Runs autoCreate() on DOMContentLoaded automatically
  enableAutoCreate();
</script>

5. The library uses the native alert() by default when it needs to show a message (for example, when a selection limit is hit). Replace it with your own handler using setMessageHandler().

import { setMessageHandler } from 'dist/searchdown';

// Replace the default alert with a toast notification
// The handler receives a message string and a type: "success" or "error"
setMessageHandler((text, type) => {
  MyToast.show(text, { level: type, timeout: 4000 });
});

// Reset back to the default browser alert behavior
setMessageHandler(null);

6. Check whether the selection meets the required minimum. Returns true if valid, false if not.

import { validate, reportValidity } from 'dist/searchdown';

const isValid = validate('#role-picker');

// Run the same check, then surface the browser's native validation UI
reportValidity('#role-picker');

7. Set & get the selected values.

// Get the current selection
// Returns a string for single-select, an array for multi-select
const current = getValue('#language-picker');

// Set selections programmatically
// Clears existing selections, then applies the supplied values
setValue('#language-picker', ['TypeScript', 'Rust']);

// Pass true as the second argument to include text currently typed in the input
const withTyped = getValue('#language-picker', true);

8. All configuration options.

• values (string[] or object): The list of available options. Pass an array of strings or a key-value object for label-to-value mapping.
• sort (string): Sort order for displayed options. Accepts 'ASC' or 'DESC'. Options appear in source order by default.
• limit (number): Maximum number of options shown in the dropdown. 0 means no limit.
• enteredLimit (number): Maximum number of selections a user can make. 0 means no limit. Requires multiple: true when set above 0.
• multiple (boolean): Allows multiple selections. Defaults to false. Mutually exclusive with simpleInput.
• addValues (boolean): Lets the user type and submit custom values not present in the original list. Defaults to false.
• saveEntered (boolean): Saves user-entered custom values back to the options list for reuse in the same session. Requires addValues: true.
• hideEntered (boolean): Removes already-selected options from the visible dropdown. Defaults to false.
• allowDuplicates (boolean): Permits the same value to be selected more than once. Defaults to false.
• caseSensitive (boolean): Applies case-sensitive matching during search. Defaults to false.
• placeholder (string): Text shown in the search input when empty. Defaults to 'Search'.
• required (number or boolean): Minimum number of required selections. true is treated as 1.
• maxHeight (number): Maximum dropdown height in pixels. Defaults to 600.
• inputName (string): The name attribute on the hidden form input. Auto-generated from an internal counter when omitted.
• initialValues (string[]): Values pre-selected when the component initializes.
• simpleInput (boolean): Switches to single-line text mode. Tags are not rendered. Mutually exclusive with multiple.
• textarea (boolean): Renders the text input as a <textarea> element.
• baseBackColor (string): Background color of the dropdown container.
• selectedBackColor (string): Background color of selected tag items.
• hoverBackColor (string): Background color on option hover.
• baseTextColor (string): Text color inside the dropdown.
• selectedTextColor (string): Text color of selected tag items.
• hoverTextColor (string): Text color on option hover.
• onChange (function): Callback invoked on every selection change. Receives (element, value).

9. API methods.

// Initialize Searchdown on a target element
// Returns { element, options } on success, false if the element is not found
searchdown('#city-picker', {
  values: ['London', 'Paris', 'Berlin', 'Madrid'],
  placeholder: 'Type a city...'
});

// Get the current selected value(s)
// Single-select returns a string; multi-select returns an array
getValue('#city-picker');

// Include text currently typed in the input field but not yet confirmed
getValue('#city-picker', true);

// Set selected values programmatically
// Clears current selections, then applies the new ones
setValue('#city-picker', ['Berlin', 'Paris']);

// Check validity against the required option
// Returns true if the selection count meets the minimum
validate('#city-picker');

// Run validate() and surface the browser's native validation UI
reportValidity('#city-picker');

// Initialize all elements marked with class="searchdown" and data-sd_* attributes
autoCreate();

// Register the auto-initialization routine to run on DOMContentLoaded
enableAutoCreate();

// Set a global custom notification handler for all instances
// Pass null to revert to the default browser alert()
setMessageHandler((text, type) => {
  console.log(`[${type}] ${text}`);
});

Alternatives:

• Choices.js: A configurable dropdown and tag input library with strong accessibility and ARIA support built in.
• Select2: A jQuery-based select replacement with AJAX data loading and internationalization capabilities.

The post Tagging & Searchable Dropdown with Multi-Select – Searchdown.js appeared first on CSS Script.