0
# Select2
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: select2
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install select2`
10

11
## Core Imports
12

13
```javascript
14
// ES Module
15
import 'jquery';
16
import 'select2';
17

18
// Or with script tags
19
<script src="path/to/jquery.min.js"></script>
20
<script src="path/to/select2.min.js"></script>
21
<link href="path/to/select2.min.css" rel="stylesheet" />
22
```
23

24
CommonJS:
25
```javascript
26
require('jquery');
27
require('select2');
28
```
29

30
## Basic Usage
31

32
```javascript
33
// Basic initialization
34
$('#my-select').select2();
35

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

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

49
// AJAX data source
50
$('#ajax-select').select2({
51
    ajax: {
52
        url: '/api/search',
53
        dataType: 'json',
54
        delay: 250,
55
        data: function (params) {
56
            return {
57
                q: params.term,
58
                page: params.page
59
            };
60
        },
61
        processResults: function (data, params) {
62
            return {
63
                results: data.items
64
            };
65
        }
66
    }
67
});
68
```
69

70
## Architecture
71

72
Select2 is built around several key components:
73

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

80
## Capabilities
81

82
### Initialization and Control
83

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

86
```javascript { .api }
87
// Initialize with options
88
$.fn.select2(options: Select2Options): jQuery;
89

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

95
// Global defaults
96
$.fn.select2.defaults: DefaultsManager;
97
```
98

99
[Initialization and Control](./initialization.md)
100

101
### Configuration Options
102

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

105
```javascript { .api }
106
interface Select2Options {
107
    // Data options
108
    ajax?: AjaxOptions;
109
    data?: DataObject[];
110
    
111
    // UI options
112
    placeholder?: string | PlaceholderObject;
113
    allowClear?: boolean;
114
    multiple?: boolean;
115
    disabled?: boolean;
116
    
117
    // Search and filtering
118
    minimumInputLength?: number;
119
    maximumInputLength?: number;
120
    maximumSelectionLength?: number;
121
    minimumResultsForSearch?: number;
122
    
123
    // Display customization
124
    templateResult?: (result: DataObject) => string | jQuery;
125
    templateSelection?: (selection: DataObject) => string | jQuery;
126
    
127
    // Behavior options
128
    closeOnSelect?: boolean;
129
    selectOnClose?: boolean;
130
    scrollAfterSelect?: boolean;
131
    
132
    // Advanced options
133
    width?: string;
134
    theme?: string;
135
    language?: string | object | string[];
136
    debug?: boolean;
137
    dropdownAutoWidth?: boolean;
138
    escapeMarkup?: (markup: string) => string;
139
    matcher?: (params: any, data: DataObject) => DataObject | null;
140
    sorter?: (data: DataObject[]) => DataObject[];
141
    
142
    // AMD configuration
143
    amdBase?: string;
144
    amdLanguageBase?: string;
145
}
146
```
147

148
[Configuration Options](./configuration.md)
149

150
### Event System
151

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

154
```javascript { .api }
155
// Event binding
156
$(selector).on('select2:open', function(e) { /* ... */ });
157
$(selector).on('select2:select', function(e) { 
158
    var data = e.params.data;
159
});
160

161
// Preventable events
162
$(selector).on('select2:opening', function(e) {
163
    e.preventDefault(); // Prevents opening
164
});
165
```
166

167
[Event System](./events.md)
168

169
### Data Management
170

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

173
```javascript { .api }
174
interface DataObject {
175
    id: string | number;
176
    text: string;
177
    selected?: boolean;
178
    disabled?: boolean;
179
    element?: HTMLOptionElement;
180
}
181

182
interface GroupedDataObject {
183
    text: string;
184
    children: DataObject[];
185
}
186
```
187

188
[Data Management](./data-management.md)
189

190
### AJAX Integration
191

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

194
```javascript { .api }
195
interface AjaxOptions {
196
    url: string | ((params: AjaxParams) => string);
197
    data?: (params: AjaxParams) => object;
198
    processResults?: (data: any, params: AjaxParams) => AjaxResponse;
199
    transport?: (params: TransportParams, success: Function, failure: Function) => void;
200
    delay?: number;
201
    cache?: boolean;
202
}
203
```
204

205
[AJAX Integration](./ajax.md)
206

207
### Theming and Customization
208

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

211
```javascript { .api }
212
interface ThemeOptions {
213
    theme?: string;
214
    containerCss?: object;
215
    containerCssClass?: string;
216
    dropdownCss?: object;
217
    dropdownCssClass?: string;
218
    templateResult?: (result: DataObject) => string | jQuery;
219
    templateSelection?: (selection: DataObject) => string | jQuery;
220
}
221
```
222

223
[Theming and Customization](./theming.md)
224

225
## Types
226

227
```javascript { .api }
228
// Core data structure
229
interface DataObject {
230
    id: string | number;
231
    text: string;
232
    selected?: boolean;
233
    disabled?: boolean;
234
    element?: HTMLOptionElement;
235
}
236

237
// Placeholder configuration
238
interface PlaceholderObject {
239
    id: string;
240
    text: string;
241
}
242

243
// AJAX request parameters
244
interface AjaxParams {
245
    term: string;
246
    page: number;
247
}
248

249
// AJAX response format
250
interface AjaxResponse {
251
    results: DataObject[];
252
    pagination?: {
253
        more: boolean;
254
    };
255
}
256

257
// Event parameters
258
interface EventParams {
259
    data?: DataObject;
260
    originalEvent?: Event;
261
}
262
```