ng-select2-component 16.0.0 → 17.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AUTHORS.md +8 -8
- package/CHANGELOG.md +246 -150
- package/README.md +135 -121
- package/fesm2022/ng-select2-component.mjs +601 -597
- package/fesm2022/ng-select2-component.mjs.map +1 -1
- package/lib/select2-hint.component.d.ts +1 -1
- package/lib/select2-hint.component.d.ts.map +1 -1
- package/lib/select2-interfaces.d.ts +10 -6
- package/lib/select2-interfaces.d.ts.map +1 -1
- package/lib/select2-label.component.d.ts +1 -1
- package/lib/select2-label.component.d.ts.map +1 -1
- package/lib/select2-utils.d.ts +12 -8
- package/lib/select2-utils.d.ts.map +1 -1
- package/lib/select2.component.d.ts +128 -122
- package/lib/select2.component.d.ts.map +1 -1
- package/package.json +1 -1
- package/public_api.d.ts +2 -4
- package/public_api.d.ts.map +1 -1
- package/lib/select2.module.d.ts +0 -14
- package/lib/select2.module.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -12,61 +12,69 @@ npm i ng-select2-component --save
|
|
|
12
12
|
|
|
13
13
|
## Requirements
|
|
14
14
|
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
15
|
+
- peerDependencies:
|
|
16
|
+
|
|
17
|
+
- `angular` 19.0.0 and more
|
|
18
|
+
- `angular/cdk` 19.0.0 and more
|
|
19
|
+
|
|
20
|
+
- dependencies (include):
|
|
21
|
+
|
|
22
|
+
- `ngx-infinite-scroll` 19.0.0 and more
|
|
23
|
+
|
|
24
|
+
### Notes
|
|
25
|
+
|
|
26
|
+
| Version | For **Angular** | Notes |
|
|
27
|
+
| --------- | --------------- | ----------------- |
|
|
28
|
+
| `17.1.0` | 19 and more | Ivy / Stand-alone |
|
|
29
|
+
| `16.0.0` | 19 | Ivy / Module |
|
|
30
|
+
| `15.4.0` | 18 | Ivy |
|
|
31
|
+
| `14.0.1` | 17 | Ivy |
|
|
32
|
+
| `13.0.12` | 16.1 | Ivy |
|
|
33
|
+
| `12.1.0` | 16 | Ivy |
|
|
34
|
+
| `11.1.0` | 15 | Ivy |
|
|
35
|
+
| `10.0.0` | 14 | Ivy |
|
|
36
|
+
| `9.0.0` | 13 | Ivy |
|
|
37
|
+
| `8.1.0` | 10, 11 and 12 | View Engine |
|
|
38
|
+
| `7.3.1` | 7, 8 and 9 | View Engine |
|
|
35
39
|
|
|
36
40
|
## Demo
|
|
37
41
|
|
|
38
|
-
[See a demo](https://harvest-dev.github.io/ng-select2/dist/ng-select2/browser).
|
|
42
|
+
[See a demo and code generator](https://harvest-dev.github.io/ng-select2/dist/ng-select2/browser).
|
|
39
43
|
|
|
40
44
|
## Features
|
|
41
45
|
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
46
|
+
- select one
|
|
47
|
+
- options or groups (list or grid)
|
|
48
|
+
- scroll
|
|
49
|
+
- local search
|
|
50
|
+
- select by keyboard
|
|
51
|
+
- disabled option
|
|
52
|
+
- disabled component
|
|
53
|
+
- hide search box
|
|
54
|
+
- placeholder
|
|
55
|
+
- multiple selection
|
|
56
|
+
- add items not found in multiple
|
|
57
|
+
- material style
|
|
58
|
+
- form binding
|
|
59
|
+
- templating
|
|
60
|
+
- etc.
|
|
56
61
|
|
|
57
62
|
## Usage
|
|
58
63
|
|
|
59
64
|
### example
|
|
60
65
|
|
|
61
66
|
```ts
|
|
62
|
-
import {
|
|
67
|
+
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
|
|
68
|
+
|
|
69
|
+
import { Select2, Select2Hint, Select2Label } from 'ng-select2-component';
|
|
63
70
|
|
|
64
|
-
@
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
71
|
+
@Component({
|
|
72
|
+
selector: 'my-component',
|
|
73
|
+
templateUrl: './my-component.component.html',
|
|
74
|
+
styleUrls: ['./my-component.component.scss'],
|
|
75
|
+
imports: [FormsModule, ReactiveFormsModule, Select2, Select2Hint, Select2Label],
|
|
68
76
|
})
|
|
69
|
-
class
|
|
77
|
+
class MyComponent {}
|
|
70
78
|
```
|
|
71
79
|
|
|
72
80
|
```html
|
|
@@ -75,58 +83,52 @@ class MainModule {}
|
|
|
75
83
|
|
|
76
84
|
### properties and events of the component
|
|
77
85
|
|
|
78
|
-
| name | type
|
|
79
|
-
| ------------------------------------------------------------------------- |
|
|
80
|
-
| `data`
|
|
81
|
-
| `value` | [`Select2Value`](#select2-data-structure)
|
|
82
|
-
| `minCharForSearch` | `number`
|
|
83
|
-
| `minCountForSearch` | `number`
|
|
84
|
-
| `displaySearchStatus` | `'default'`<br>`'hidden'`<br>`'always'`
|
|
85
|
-
| `placeholder` | `string`
|
|
86
|
-
| `noResultMessage` | `string`
|
|
87
|
-
| `customSearchEnabled` | `boolean`
|
|
88
|
-
| `multiple` | `boolean`
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `(
|
|
116
|
-
| `(
|
|
117
|
-
| `(
|
|
118
|
-
| `(
|
|
119
|
-
| `(
|
|
120
|
-
| `(
|
|
121
|
-
| `(
|
|
122
|
-
| `(
|
|
123
|
-
|
|
124
|
-
@Input() selectionOverride: Select2SelectionOverride;
|
|
125
|
-
|
|
126
|
-
/** force selection on one line */
|
|
127
|
-
@HostBinding('class.select2-selection-nowrap')
|
|
128
|
-
@Input({ transform: booleanAttribute })
|
|
129
|
-
selectionNoWrap = false;
|
|
86
|
+
| name | type | default | description | required |
|
|
87
|
+
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
88
|
+
| `data` (required) | [`Select2Data`](#select2-data-structure) | | the data of the select2 | |
|
|
89
|
+
| `value` | [`Select2Value`](#select2-data-structure) | | initial value | |
|
|
90
|
+
| `minCharForSearch` | `number` | `0` | start the search when the number of characters is reached (`0` = unlimited) | |
|
|
91
|
+
| `minCountForSearch` | `number` | `6` | hide search box if `options.length < minCountForSearch` | |
|
|
92
|
+
| `displaySearchStatus` | `'default'`<br>`'hidden'`<br>`'always'` | `'default'` | display the search box (`default` : is based on `minCountForSearch`) | |
|
|
93
|
+
| `placeholder` | `string` | | the placeholder string if nothing selected | |
|
|
94
|
+
| `noResultMessage` | `string` | | the message string if no results when using the search field | |
|
|
95
|
+
| `customSearchEnabled` | `boolean` | `false` | will trigger `search` event, and disable inside filter | |
|
|
96
|
+
| `multiple` | `boolean` | `false` | select multiple options | |
|
|
97
|
+
| `multipleDrag` | `boolean` | `false` | drag'n drop list of items in selection | with `multiple` |
|
|
98
|
+
| `resettable` | `boolean` | `false` | add a button to reset value | |
|
|
99
|
+
| `resetSelectedValue` | `any` | `undefined` | selected option when × is clicked | |
|
|
100
|
+
| `autoCreate` | `boolean` | `false` | gives the possibility to add elements not present in the list. | |
|
|
101
|
+
| `limitSelection` | `number` | `0` | to limit multiple selection (`0` = unlimited) | |
|
|
102
|
+
| `hideSelectedItems` | `boolean` | `false` | remove selected values | with `multiple` |
|
|
103
|
+
| `resultMaxHeight` | `string` | `'200px'` | change the height size of results | |
|
|
104
|
+
| `maxResults` | `number` | `0` | maximum results limit (`0` = unlimited) | |
|
|
105
|
+
| `maxResultsMessage` | `string` | `'Too much result…'` | message when maximum result | |
|
|
106
|
+
| `grid` | `number` or `string` | | option by line in grid layout (empty or `0` = no grid layout)<br>`number`: item by line<br>`string`: minimal item width | |
|
|
107
|
+
| `listPosition` | `'below'`<br>`'above'`<br>`'auto'` ¹ | `'below'` | the position for the dropdown list | ¹ `'auto'`: only with `overlay` |
|
|
108
|
+
| `infiniteScroll` | `boolean` | `false` | active infiniteScroll on dropdown list | with `ngx-infinite-scroll` |
|
|
109
|
+
| `infiniteScrollDistance` | `number` | `1.5` | infiniteScroll distance | with `ngx-infinite-scroll` |
|
|
110
|
+
| `infiniteScrollThrottle` | `number` | `150` | infiniteScroll throttle | |
|
|
111
|
+
| `overlay` | `boolean` | `false` | active an overlay mode for dropdown list (with angular cdk). (See [Overlay](#overlay)) | |
|
|
112
|
+
| `styleMode` | `'default'`<br>`'material'`<br>`'noStyle'`<br>`'borderless'` | `'default'` | change style for material style or remove border and background color | |
|
|
113
|
+
| `templates` | [`Select2Template`](#select2-data-structure)<br>(see ”possible object” in [Templating](#templating)) | | use templates for formatting content (see [Templating](#templating)) | |
|
|
114
|
+
| `templateSelection` | `TemplateRef` | | use templates for formatting content (see [Templating](#templating)) | |
|
|
115
|
+
| `noLabelTemplate` | `boolean` | `false` | do not use the template in the selection, stay in text mode | |
|
|
116
|
+
| `selectionOverride` | [`Select2SelectionOverride`](#select2-data-structure) | | Replace selection by a text<br>`string`: `%size%` = total selected options<br>`function`: juste show the string | |
|
|
117
|
+
| `selectionNoWrap` | `boolean` | `false` | Force selection on one line | |
|
|
118
|
+
| `showSelectAll` | `boolean` | `false` | Add an option to select all options | with `multiple` |
|
|
119
|
+
| `selectAllText` | `string` | `'Select all'` | Text when all options as not selected | with `multiple` |
|
|
120
|
+
| `removeAllText` | `string` | `'Remove all'` | Text when all options as selected | with `multiple` |
|
|
121
|
+
| `editPattern` | `(str: string) => string` | | use it for change the pattern of the filter search | |
|
|
122
|
+
| `ngModel`<br>`id`<br>`required`<br>`disabled`<br>`readonly`<br>`tabIndex` | | | just like a `select` control | |
|
|
123
|
+
| `(update)` | `(event: `[`Select2UpdateEvent`](#select2-data-structure)`) => void` | | triggered when user select an option | |
|
|
124
|
+
| `(open)` | `(event: Select2) => void` | | triggered when user open the options | |
|
|
125
|
+
| `(close)` | `(event: Select2) => void` | | triggered when user close the options | |
|
|
126
|
+
| `(focus)` | `(event: Select2) => void` | | triggered when user enters the component | |
|
|
127
|
+
| `(blur)` | `(event: Select2) => void` | | triggered when user leaves the component | |
|
|
128
|
+
| `(search)` | `(event: `[`Select2SearchEvent`](#select2-data-structure)`) => void` | | triggered when search text changed | with `customSearchEnabled` |
|
|
129
|
+
| `(scroll)` | `(event: `[`Select2ScrollEvent`](#select2-data-structure)`) => void` | | triggered when infiniteScroll is on `up` or `down` position | with `ngx-infinite-scroll` |
|
|
130
|
+
| `(removeOption)` | `(event: `[`Select2RemoveEvent`](#select2-data-structure)`) => void` | | triggered when an option is removed from the list of selected options options list | with `multiple` |
|
|
131
|
+
| `(autoCreateItem)` | `(event: `[`Select2AutoCreateEvent`](#select2-data-structure)`) => void` | | triggered when a new item has been added | with `autoCreate` |
|
|
130
132
|
|
|
131
133
|
### select2 data structure
|
|
132
134
|
|
|
@@ -138,7 +140,7 @@ export interface Select2Group {
|
|
|
138
140
|
options: Select2Option[];
|
|
139
141
|
/** add classes */
|
|
140
142
|
classes?: string;
|
|
141
|
-
/** template id
|
|
143
|
+
/** template id dropdown & selection if no templateSelectionId */
|
|
142
144
|
templateId?: string;
|
|
143
145
|
/** template data */
|
|
144
146
|
data?: any;
|
|
@@ -155,17 +157,19 @@ export interface Select2Option {
|
|
|
155
157
|
id?: string;
|
|
156
158
|
/** add classes */
|
|
157
159
|
classes?: string;
|
|
158
|
-
/** template id
|
|
160
|
+
/** template id dropdown & selection if no templateSelectionId */
|
|
159
161
|
templateId?: string;
|
|
162
|
+
/** template id for selection */
|
|
163
|
+
templateSelectionId?: string;
|
|
160
164
|
/** template data */
|
|
161
165
|
data?: any;
|
|
162
166
|
/** hide this option */
|
|
163
167
|
hide?: boolean;
|
|
164
168
|
}
|
|
165
169
|
|
|
166
|
-
export type Select2Value = string | number | boolean | object;
|
|
170
|
+
export type Select2Value = string | number | boolean | object | null | undefined;
|
|
167
171
|
|
|
168
|
-
export type Select2UpdateValue = Select2Value | Select2Value[];
|
|
172
|
+
export type Select2UpdateValue = Select2Value | Select2Value[] | undefined | null;
|
|
169
173
|
|
|
170
174
|
export type Select2Data = (Select2Group | Select2Option)[];
|
|
171
175
|
|
|
@@ -173,9 +177,9 @@ export interface Select2UpdateEvent<U extends Select2UpdateValue = Select2Value>
|
|
|
173
177
|
/** component */
|
|
174
178
|
readonly component: Select2;
|
|
175
179
|
/** current selected value */
|
|
176
|
-
readonly value: U;
|
|
180
|
+
readonly value: U | null;
|
|
177
181
|
/** selected option */
|
|
178
|
-
readonly options: Select2Option[];
|
|
182
|
+
readonly options: Select2Option[] | null;
|
|
179
183
|
}
|
|
180
184
|
|
|
181
185
|
export interface Select2AutoCreateEvent<U extends Select2UpdateValue = Select2Value> {
|
|
@@ -184,14 +188,14 @@ export interface Select2AutoCreateEvent<U extends Select2UpdateValue = Select2Va
|
|
|
184
188
|
/** current selected value */
|
|
185
189
|
readonly value: U;
|
|
186
190
|
/** selected option */
|
|
187
|
-
readonly options: Select2Option[];
|
|
191
|
+
readonly options: Select2Option[] | null;
|
|
188
192
|
}
|
|
189
193
|
|
|
190
194
|
export interface Select2SearchEvent<U extends Select2UpdateValue = Select2Value> {
|
|
191
195
|
/** component */
|
|
192
196
|
readonly component: Select2;
|
|
193
197
|
/** current selected value */
|
|
194
|
-
readonly value: U;
|
|
198
|
+
readonly value: U | null;
|
|
195
199
|
/** search text */
|
|
196
200
|
readonly search: string;
|
|
197
201
|
/** current data source */
|
|
@@ -221,6 +225,8 @@ export interface Select2ScrollEvent {
|
|
|
221
225
|
}
|
|
222
226
|
|
|
223
227
|
export type Select2SelectionOverride = string | ((params: { size: number; options: Select2Option[] | null }) => string);
|
|
228
|
+
|
|
229
|
+
export type Select2Template = TemplateRef<any> | { [key: string]: TemplateRef<any> } | undefined;
|
|
224
230
|
```
|
|
225
231
|
|
|
226
232
|
### Templating
|
|
@@ -286,39 +292,47 @@ const data: Select2Data = [
|
|
|
286
292
|
];
|
|
287
293
|
```
|
|
288
294
|
|
|
295
|
+
#### Template for change the selection
|
|
296
|
+
|
|
297
|
+
```html
|
|
298
|
+
<select2 [data]="data" [templateSelection]="templateSelection">
|
|
299
|
+
<ng-template #templateSelection let-data="data"><strong>{{ data?.color }}</strong> ({{ data?.name }})</ng-template>
|
|
300
|
+
</select2>
|
|
301
|
+
```
|
|
302
|
+
|
|
289
303
|
#### Possible object
|
|
290
304
|
|
|
291
|
-
-
|
|
292
|
-
-
|
|
293
|
-
-
|
|
294
|
-
-
|
|
305
|
+
- `TemplateRef`
|
|
306
|
+
- `{template: TemplateRef}`
|
|
307
|
+
- `{option?: TemplateRef, group?: TemplateRef}`
|
|
308
|
+
- `{templateId1: TemplateRef, ...}`
|
|
295
309
|
|
|
296
310
|
In addition to the rendering templates of options and groups, in addition to going through the `templateSelection` attribute, it is possible to define that of the selection :
|
|
297
311
|
|
|
298
|
-
-
|
|
299
|
-
-
|
|
312
|
+
- `{templateSelection: TemplateRef}`
|
|
313
|
+
- `{optionSelection: TemplateRef}`
|
|
300
314
|
|
|
301
315
|
#### Priority order
|
|
302
316
|
|
|
303
317
|
For group or option:
|
|
304
318
|
|
|
305
|
-
-
|
|
306
|
-
-
|
|
307
|
-
-
|
|
308
|
-
-
|
|
309
|
-
-
|
|
319
|
+
- `'id'` (from item data `templateId`)
|
|
320
|
+
- `'group'` or `'option'`
|
|
321
|
+
- `'template'`
|
|
322
|
+
- `TemplateRef` (from html attribute `templates`)
|
|
323
|
+
- Default render
|
|
310
324
|
|
|
311
325
|
For the selection:
|
|
312
326
|
|
|
313
|
-
-
|
|
314
|
-
-
|
|
315
|
-
-
|
|
316
|
-
-
|
|
317
|
-
-
|
|
318
|
-
-
|
|
319
|
-
-
|
|
320
|
-
-
|
|
321
|
-
-
|
|
327
|
+
- `'id'` (from item data `templateSelectionId`)
|
|
328
|
+
- `'optionSelection'`
|
|
329
|
+
- `'templateSelection'`
|
|
330
|
+
- `TemplateRef` (from html attribute `templateSelection`)
|
|
331
|
+
- `'id'` (from item data `templateId`)
|
|
332
|
+
- `'option'`
|
|
333
|
+
- `'template'`
|
|
334
|
+
- `TemplateRef` (from html attribute `templates`)
|
|
335
|
+
- Default render
|
|
322
336
|
|
|
323
337
|
### Overlay
|
|
324
338
|
|