Advanced Select

Advanced select solutions for massive datasets.

Contents

• Overview
• Installation
• Basic usage
• Configuration Options
• JavaScript API
• Events
• Common Patterns
• License

Overview

The Advanced Select component provides a customizable dropdown select interface with support for search, tags, API integration, and extensive styling options. It's designed for handling large datasets and complex selection scenarios.

Key Features:

• Search functionality
• Tags mode for multiple selections
• API integration for dynamic options
• Custom templates and styling
• Multiple selection support
• Option grouping
• Icons and descriptions for options
• Programmatic control via JavaScript API
• Event system for selection tracking

Installation

To get started, install Select plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i @preline/select

Some positioning features require Floating UI. Install it if you plan to use dropdownScope: "window", dropdownPlacement, or dropdownAutoPlacement:

npm i @floating-ui/dom

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/select */
@source "../node_modules/@preline/select/*.js";
@import "./node_modules/@preline/select/variants.css";
@import "./node_modules/@preline/select/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag. If you use dropdownScope: "window", dropdownPlacement, or dropdownAutoPlacement, also load the Floating UI UMD bundle before the plugin. It exposes the FloatingUIDOM global the plugin relies on.

<!-- Optional: required for dropdownScope: "window", dropdownPlacement, dropdownAutoPlacement -->
<script src="https://cdn.jsdelivr.net/npm/@floating-ui/dom@latest/dist/floating-ui.dom.umd.min.js"></script>
<script src="./node_modules/@preline/select/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<!-- Optional: required for dropdownScope: "window", dropdownPlacement, dropdownAutoPlacement -->
<script src="https://cdn.jsdelivr.net/npm/@floating-ui/dom@latest/dist/floating-ui.dom.umd.min.js"></script>
<script type="module">
  import HSSelect from "@preline/select/non-auto.mjs";

  new HSSelect(document.querySelector("#select"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module. If you use dropdownScope: "window", dropdownPlacement, or dropdownAutoPlacement, expose FloatingUIDOM on window before importing the plugin.

@preline/select is the auto-init entry: it scans the DOM and initializes matching elements automatically.

// Optional: required for dropdownScope: "window", dropdownPlacement, dropdownAutoPlacement
import * as FloatingUIDOM from "@floating-ui/dom";
window.FloatingUIDOM = FloatingUIDOM;

import "@preline/select";

@preline/select/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

// Optional: required for dropdownScope: "window", dropdownPlacement, dropdownAutoPlacement
import * as FloatingUIDOM from "@floating-ui/dom";
window.FloatingUIDOM = FloatingUIDOM;

import HSSelect from "@preline/select/non-auto";

HSSelect.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#select");
if (el) new HSSelect(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for an advanced select component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The component transforms a standard select element into an advanced dropdown.

<select data-hs-select='{
    "placeholder": "Select option...",
    "toggleTag": "<button type=\"button\"></button>",
    "toggleClasses": "",
    "dropdownClasses": "",
    "optionClasses": "hs-selected:"
  }'>
  <option>Select option</option>
  <option>Name</option>
  <option>Email address</option>
  <option>Description</option>
  <option>User ID</option>
</select>

Structure Requirements:

• data-hs-select: Required on the <select> element, contains configuration options as JSON
• Standard <option> elements inside the select
• Optional <optgroup> elements for grouping

Initial State:

• Select displays placeholder text when no option is selected
• Dropdown is closed by default

Configuration Options

Data Options

Data options are specified in the data-hs-select attribute as a JSON object.

Tailwind Modifiers

JavaScript API

The HSSelect object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a select instance.

Static Methods

These methods are called directly on the HSSelect class.

Usage Examples

Example 1: Opening and closing dropdown

// Get the select instance
const instance = HSSelect.getInstance('#hs-select', true);

if (instance) {
  const { element } = instance;

  // Open dropdown
  element.open();

  // Close dropdown
  element.close();
}

Example 2: Setting value programmatically

const instance = HSSelect.getInstance('#hs-select', true);

if (instance) {
  const { element } = instance;

  // Set value for single select
  element.setValue('option-value');

  // Set value for multiple select
  element.setValue(['value-1', 'value-2']);
}

Example 3: Adding and removing options

const instance = HSSelect.getInstance('#hs-select', true);

if (instance) {
  const { element } = instance;

  // Add option
  element.addOption({
    title: 'New Option',
    val: 'new-option',
    options: {
      description: 'Option description',
      icon: '<svg>...</svg>'
    }
  });

  // Remove option
  element.removeOption('new-option');
}

Example 4: Destroying select instance

const instance = HSSelect.getInstance('#hs-select', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-select').remove();
  });
}

Events

Select instances emit events that can be listened to for selection lifecycle hooks.

Event Usage Example

// Get select instance
const instance = HSSelect.getInstance('#hs-select', true);

if (instance) {
  const { element } = instance;

  // Listen for selection changes
  element.on('change', (value) => {
    console.log('Selected value:', value);
    // value is a string for single-select, string[] for multi-select / tags mode
  });
}

Common Patterns

Pattern 1: Search Enabled

Enable search functionality in dropdown.

<select data-hs-select='{
  "hasSearch": true,
  "searchPlaceholder": "Search options..."
}'>
  <!-- Options -->
</select>

Pattern 2: Tags Mode

Use tags mode for multiple selections.

<select multiple data-hs-select='{
  "mode": "tags"
}'>
  <!-- Options -->
</select>

Pattern 3: API Integration

Load options from API.

<select data-hs-select='{
  "apiUrl": "/api/options",
  "apiFieldsMap": {
    "id": "id",
    "title": "name",
    "val": "value"
  }
}'>
  <!-- Options -->
</select>

License

Copyright (c) 2026 Preline Labs.

Licensed under the MIT License.