0
# Configuration Options
1

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

4
## Capabilities
5

6
### Core Configuration Interface
7

8
Main configuration object with all available options for customizing Select2 behavior.
9

10
```javascript { .api }
11
/**
12
 * Complete Select2 configuration options
13
 */
14
interface Select2Options {
15
    // Data Source Options
16
    ajax?: AjaxOptions;
17
    data?: DataObject[];
18
    
19
    // Basic UI Options
20
    placeholder?: string | PlaceholderObject;
21
    allowClear?: boolean;
22
    multiple?: boolean;
23
    disabled?: boolean;
24
    
25
    // Search and Input Options
26
    minimumInputLength?: number;
27
    maximumInputLength?: number;
28
    minimumResultsForSearch?: number;
29
    
30
    // Selection Limits
31
    maximumSelectionLength?: number;
32
    
33
    // Display and Styling
34
    width?: string;
35
    theme?: string;
36
    containerCss?: object;
37
    containerCssClass?: string;
38
    dropdownCss?: object;
39
    dropdownCssClass?: string;
40
    dropdownParent?: jQuery;
41
    dropdownAutoWidth?: boolean;
42
    
43
    // Template Functions
44
    templateResult?: (result: DataObject) => string | jQuery;
45
    templateSelection?: (selection: DataObject) => string | jQuery;
46
    escapeMarkup?: (markup: string) => string;
47
    
48
    // Behavior Options
49
    closeOnSelect?: boolean;
50
    selectOnClose?: boolean;
51
    scrollAfterSelect?: boolean;
52
    
53
    // Advanced Options
54
    language?: string | object | string[];
55
    matcher?: (params: SearchParams, data: DataObject) => DataObject | null;
56
    sorter?: (data: DataObject[]) => DataObject[];
57
    
58
    // Tag Options
59
    tags?: boolean | string[];
60
    tokenSeparators?: string[];
61
    tokenizer?: (input: string, selection: DataObject[], selectCallback: Function, options: any) => string;
62
    createTag?: (params: CreateTagParams) => DataObject | null;
63
    insertTag?: (data: DataObject[], tag: DataObject) => void;
64
    
65
    // Adapter Overrides
66
    dataAdapter?: any;
67
    resultsAdapter?: any;
68
    selectionAdapter?: any;
69
    dropdownAdapter?: any;
70
    
71
    // Debug Options
72
    debug?: boolean;
73
}
74
```
75

76
### Basic UI Configuration
77

78
Essential options for controlling Select2's appearance and basic behavior.
79

80
```javascript { .api }
81
/**
82
 * Placeholder configuration
83
 */
84
interface PlaceholderObject {
85
    id: string;
86
    text: string;
87
}
88

89
// Basic UI options
90
placeholder?: string | PlaceholderObject;
91
allowClear?: boolean;        // Enable clear button (single select only)
92
multiple?: boolean;          // Enable multi-select mode
93
disabled?: boolean;          // Disable the control
94
width?: string;             // Control width: 'resolve', 'element', 'style', or CSS value
95
theme?: string;             // Theme name (default: 'default')
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
// Basic placeholder
102
$('#select1').select2({
103
    placeholder: "Choose an option"
104
});
105

106
// Placeholder object with ID
107
$('#select2').select2({
108
    placeholder: {
109
        id: "",
110
        text: "Select something..."
111
    }
112
});
113

114
// Multi-select with clear
115
$('#multi-select').select2({
116
    multiple: true,
117
    allowClear: true,
118
    width: '100%'
119
});
120

121
// Custom width and theme
122
$('#themed-select').select2({
123
    width: '300px',
124
    theme: 'bootstrap4'
125
});
126
```
127

128
### Search and Input Configuration
129

130
Options controlling search behavior, input validation, and filtering.
131

132
```javascript { .api }
133
// Search configuration
134
minimumInputLength?: number;        // Minimum characters before search (default: 0)
135
maximumInputLength?: number;        // Maximum input length (default: 0 = unlimited)
136
minimumResultsForSearch?: number;   // Minimum results to show search box (default: 0)
137
maximumSelectionLength?: number;    // Maximum selections for multi-select (default: 0 = unlimited)
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
// Require minimum input for search
144
$('#search-select').select2({
145
    minimumInputLength: 2,
146
    ajax: {
147
        url: '/api/search',
148
        // ... ajax config
149
    }
150
});
151

152
// Limit input length and selections
153
$('#limited-select').select2({
154
    multiple: true,
155
    maximumInputLength: 50,
156
    maximumSelectionLength: 3
157
});
158

159
// Hide search box for small result sets
160
$('#no-search-select').select2({
161
    minimumResultsForSearch: 10
162
});
163
```
164

165
### Display and Styling Configuration
166

167
Options for customizing appearance, CSS, and rendering templates.
168

169
```javascript { .api }
170
// Styling options
171
containerCss?: object;              // CSS styles for main container
172
containerCssClass?: string;         // CSS classes for main container  
173
dropdownCss?: object;              // CSS styles for dropdown
174
dropdownCssClass?: string;         // CSS classes for dropdown
175
dropdownParent?: jQuery;           // Custom dropdown container
176
dropdownAutoWidth?: boolean;       // Auto-size dropdown width
177

178
// Template functions
179
templateResult?: (result: DataObject) => string | jQuery;
180
templateSelection?: (selection: DataObject) => string | jQuery;
181
escapeMarkup?: (markup: string) => string;
182
```
183

184
**Usage Examples:**
185

186
```javascript
187
// Custom CSS styling
188
$('#styled-select').select2({
189
    containerCss: {
190
        'border-radius': '0px',
191
        'border': '2px solid #blue'
192
    },
193
    containerCssClass: 'my-custom-select',
194
    dropdownCssClass: 'my-dropdown'
195
});
196

197
// Custom templates
198
$('#template-select').select2({
199
    templateResult: function(result) {
200
        if (!result.id) return result.text;
201
        
202
        return $('<span><i class="icon-' + result.id + '"></i> ' + result.text + '</span>');
203
    },
204
    templateSelection: function(selection) {
205
        return selection.text || selection.id;
206
    }
207
});
208

209
// Custom dropdown parent
210
$('#modal-select').select2({
211
    dropdownParent: $('#myModal')
212
});
213
```
214

215
### Behavior Configuration
216

217
Options controlling Select2's interactive behavior and user experience.
218

219
```javascript { .api }
220
// Behavior options
221
closeOnSelect?: boolean;        // Close dropdown after selection (default: true)
222
selectOnClose?: boolean;        // Auto-select highlighted option on close (default: false)
223
scrollAfterSelect?: boolean;    // Control scrolling after selection (default: false)
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
// Keep dropdown open after selection (useful for multi-select)
230
$('#multi-open-select').select2({
231
    multiple: true,
232
    closeOnSelect: false
233
});
234

235
// Auto-select on close
236
$('#auto-select').select2({
237
    selectOnClose: true
238
});
239
```
240

241
### Advanced Configuration
242

243
Advanced options for custom matching, sorting, and language settings.
244

245
```javascript { .api }
246
// Advanced options
247
language?: string | object | string[];
248
matcher?: (params: SearchParams, data: DataObject) => DataObject | null;
249
sorter?: (data: DataObject[]) => DataObject[];
250

251
interface SearchParams {
252
    term: string;
253
}
254
```
255

256
**Usage Examples:**
257

258
```javascript
259
// Custom language
260
$('#lang-select').select2({
261
    language: 'es'  // Spanish translations
262
});
263

264
// Custom matcher for fuzzy search
265
$('#fuzzy-select').select2({
266
    matcher: function(params, data) {
267
        if ($.trim(params.term) === '') {
268
            return data;
269
        }
270
        
271
        var term = params.term.toLowerCase();
272
        var text = data.text.toLowerCase();
273
        
274
        // Simple fuzzy matching
275
        if (text.indexOf(term) > -1) {
276
            return data;
277
        }
278
        
279
        return null;
280
    }
281
});
282

283
// Custom sorter
284
$('#sorted-select').select2({
285
    sorter: function(data) {
286
        return data.sort(function(a, b) {
287
            return a.text.localeCompare(b.text);
288
        });
289
    }
290
});
291
```
292

293
### Tag Configuration
294

295
Options for enabling and customizing tag creation functionality.
296

297
```javascript { .api }
298
// Tag options
299
tags?: boolean | string[];
300
tokenSeparators?: string[];
301
tokenizer?: (input: string, selection: DataObject[], selectCallback: Function, options: any) => string;
302
createTag?: (params: CreateTagParams) => DataObject | null;
303
insertTag?: (data: DataObject[], tag: DataObject) => void;
304

305
interface CreateTagParams {
306
    term: string;
307
}
308
```
309

310
**Usage Examples:**
311

312
```javascript
313
// Basic tag creation
314
$('#tag-select').select2({
315
    tags: true,
316
    tokenSeparators: [',', ' ']
317
});
318

319
// Predefined tags
320
$('#predefined-tags').select2({
321
    tags: ['red', 'blue', 'green', 'yellow']
322
});
323

324
// Custom tag creation
325
$('#custom-tags').select2({
326
    tags: true,
327
    createTag: function(params) {
328
        var term = $.trim(params.term);
329
        
330
        if (term === '') {
331
            return null;
332
        }
333
        
334
        return {
335
            id: term,
336
            text: term + ' (new)',
337
            newTag: true
338
        };
339
    },
340
    insertTag: function(data, tag) {
341
        // Insert at beginning
342
        data.unshift(tag);
343
    }
344
});
345
```
346

347
### Debug Configuration
348

349
Options for enabling debug output and development assistance.
350

351
```javascript { .api }
352
// Debug options
353
debug?: boolean;    // Enable debug logging to console
354
```
355

356
**Usage Examples:**
357

358
```javascript
359
// Enable debug mode
360
$('#debug-select').select2({
361
    debug: true,
362
    ajax: {
363
        url: '/api/data'
364
    }
365
});
366
```
367

368
## Configuration Validation
369

370
Select2 performs automatic validation and fallback for configuration options:
371

372
```javascript
373
// Invalid configurations are ignored or receive defaults
374
$('#select').select2({
375
    minimumInputLength: -1,    // Becomes 0
376
    width: 'invalid',          // Falls back to 'resolve'
377
    nonExistentOption: true    // Ignored silently
378
});
379
```