or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ajax.mdconfiguration.mddata-management.mdevents.mdindex.mdinitialization.mdtheming.md
tile.json

tessl/npm-select2

Select2 is a jQuery based replacement for select boxes with searching, remote data sets, and infinite scrolling support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/select2@4.0.x

To install, run

npx @tessl/cli install tessl/npm-select2@4.0.0

index.mddocs/

Select2

Select2 is a jQuery-based replacement for HTML select boxes that provides advanced features including live search functionality, remote data loading via AJAX, multi-select interfaces with tagging capabilities, and extensive customization options. It offers superior usability compared to native select boxes by supporting infinite scrolling, autocomplete functionality, and responsive design patterns.

Package Information

  • Package Name: select2
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install select2

Core Imports

// ES Module
import 'jquery';
import 'select2';

// Or with script tags
<script src="path/to/jquery.min.js"></script>
<script src="path/to/select2.min.js"></script>
<link href="path/to/select2.min.css" rel="stylesheet" />

CommonJS:

require('jquery');
require('select2');

Basic Usage

// Basic initialization
$('#my-select').select2();

// With configuration options
$('#my-select').select2({
    placeholder: "Select an option",
    allowClear: true,
    width: '100%'
});

// Multiple selection
$('#my-multi-select').select2({
    multiple: true,
    placeholder: "Choose multiple options"
});

// AJAX data source
$('#ajax-select').select2({
    ajax: {
        url: '/api/search',
        dataType: 'json',
        delay: 250,
        data: function (params) {
            return {
                q: params.term,
                page: params.page
            };
        },
        processResults: function (data, params) {
            return {
                results: data.items
            };
        }
    }
});

Architecture

Select2 is built around several key components:

  • jQuery Plugin Interface: Main entry point providing .select2() method for initialization and control
  • Adapter System: Modular architecture with configurable adapters for data handling, dropdown behavior, selection display, and results rendering
  • Event System: Comprehensive event framework with preventable events for full lifecycle control
  • Configuration System: Extensive options for customizing behavior, appearance, and data handling
  • Decorator Pattern: Extensible system allowing functional decorators to enhance core adapters

Capabilities

Initialization and Control

Core jQuery plugin methods for initializing Select2, calling instance methods, and managing global defaults.

// Initialize with options
$.fn.select2(options: Select2Options): jQuery;

// Call instance methods
$.fn.select2(method: 'open' | 'close' | 'destroy' | 'focus' | 'enable'): jQuery;
$.fn.select2(method: 'data'): DataObject[];
$.fn.select2(method: 'isEnabled' | 'isDisabled' | 'isOpen' | 'hasFocus'): boolean;

// Global defaults
$.fn.select2.defaults: DefaultsManager;

Initialization and Control

Configuration Options

Comprehensive configuration system supporting data sources, UI customization, search behavior, multi-select options, and advanced adapter settings.

interface Select2Options {
    // Data options
    ajax?: AjaxOptions;
    data?: DataObject[];
    
    // UI options
    placeholder?: string | PlaceholderObject;
    allowClear?: boolean;
    multiple?: boolean;
    disabled?: boolean;
    
    // Search and filtering
    minimumInputLength?: number;
    maximumInputLength?: number;
    maximumSelectionLength?: number;
    minimumResultsForSearch?: number;
    
    // Display customization
    templateResult?: (result: DataObject) => string | jQuery;
    templateSelection?: (selection: DataObject) => string | jQuery;
    
    // Behavior options
    closeOnSelect?: boolean;
    selectOnClose?: boolean;
    scrollAfterSelect?: boolean;
    
    // Advanced options
    width?: string;
    theme?: string;
    language?: string | object | string[];
    debug?: boolean;
    dropdownAutoWidth?: boolean;
    escapeMarkup?: (markup: string) => string;
    matcher?: (params: any, data: DataObject) => DataObject | null;
    sorter?: (data: DataObject[]) => DataObject[];
    
    // AMD configuration
    amdBase?: string;
    amdLanguageBase?: string;
}

Configuration Options

Event System

Comprehensive event framework with lifecycle events, selection events, and preventable operations for full control over Select2 behavior.

// Event binding
$(selector).on('select2:open', function(e) { /* ... */ });
$(selector).on('select2:select', function(e) { 
    var data = e.params.data;
});

// Preventable events
$(selector).on('select2:opening', function(e) {
    e.preventDefault(); // Prevents opening
});

Event System

Data Management

Data handling system supporting static arrays, HTML options, AJAX sources, and custom data adapters with standardized object formats.

interface DataObject {
    id: string | number;
    text: string;
    selected?: boolean;
    disabled?: boolean;
    element?: HTMLOptionElement;
}

interface GroupedDataObject {
    text: string;
    children: DataObject[];
}

Data Management

AJAX Integration

Remote data loading with customizable request handling, response processing, infinite scrolling, and caching support.

interface AjaxOptions {
    url: string | ((params: AjaxParams) => string);
    data?: (params: AjaxParams) => object;
    processResults?: (data: any, params: AjaxParams) => AjaxResponse;
    transport?: (params: TransportParams, success: Function, failure: Function) => void;
    delay?: number;
    cache?: boolean;
}

AJAX Integration

Theming and Customization

Appearance customization through themes, CSS classes, template functions, and custom rendering for both dropdown options and selections.

interface ThemeOptions {
    theme?: string;
    containerCss?: object;
    containerCssClass?: string;
    dropdownCss?: object;
    dropdownCssClass?: string;
    templateResult?: (result: DataObject) => string | jQuery;
    templateSelection?: (selection: DataObject) => string | jQuery;
}

Theming and Customization

Types

// Core data structure
interface DataObject {
    id: string | number;
    text: string;
    selected?: boolean;
    disabled?: boolean;
    element?: HTMLOptionElement;
}

// Placeholder configuration
interface PlaceholderObject {
    id: string;
    text: string;
}

// AJAX request parameters
interface AjaxParams {
    term: string;
    page: number;
}

// AJAX response format
interface AjaxResponse {
    results: DataObject[];
    pagination?: {
        more: boolean;
    };
}

// Event parameters
interface EventParams {
    data?: DataObject;
    originalEvent?: Event;
}