This Angular CLI module it's a fork of select2-component without Vue & React. For Vue or React, please use the original component.
npm i ng-select2-component --save
-
peerDependencies:
-
angular
19.0.0 and more -
angular/cdk
19.0.0 and more
-
-
dependencies (include):
-
ngx-infinite-scroll
19.0.0 and more
-
Note:
- For
angular
7, 8 and 9 (View Engine): use version7.3.1
.- For
angular
10, 11 and 12 (View Engine): use version8.1.0
.- For
angular
13 (Ivy): use version9.0.0
.- For
angular
14 (Ivy): use version10.0.0
.- For
angular
15 (Ivy): use version11.1.0
.- For
angular
16 (Ivy): use version12.1.0
.- For
angular
16.1 (Ivy): use version13.0.12
.- For
angular
17 (Ivy): use version14.0.1
.- For
angular
18 (Ivy): use version15.3.0
.- For
angular
19 and more (Ivy): use version16.0.0
.
- select one
- options or groups (list or grid)
- scroll
- local search
- select by keyboard
- disabled option
- disabled component
- hide search box
- placeholder
- multiple selection
- add items not found in multiple
- material style
- form binding
- templating
import { Select2Module } from 'ng-select2-component';
@NgModule({
imports: [BrowserModule, FormsModule, Select2Module],
declarations: [MainComponent],
bootstrap: [MainComponent],
})
class MainModule {}
<select2 [data]="data" [value]="value" (update)="update($event)"> </select2>
name | type | status | default | description | required |
---|---|---|---|---|---|
data |
Select2Data |
required | the data of the select2 | ||
value |
Select2Value |
initial value | |||
minCharForSearch |
number |
0 |
start the search when the number of characters is reached (0 = unlimited) |
||
minCountForSearch |
number |
6 |
hide search box if options.length < minCountForSearch
|
||
displaySearchStatus |
'default' 'hidden' 'always'
|
'default' |
display the search box (default : is based on minCountForSearch ) |
||
placeholder |
string |
the placeholder string if nothing selected | |||
noResultMessage |
string |
the message string if no results when using the search field | |||
customSearchEnabled |
boolean |
false |
will trigger search event, and disable inside filter |
||
multiple |
boolean |
false |
select multiple options | ||
resettable |
boolean |
false |
add a button to reset value | not multiple
|
|
resetSelectedValue |
any |
undefined |
selected option when × is clicked | not multiple and with resettable
|
|
autoCreate |
boolean |
false |
gives the possibility to add elements not present in the list. | ||
limitSelection |
number |
0 |
to limit multiple selection (0 = unlimited) |
||
hideSelectedItems |
boolean |
false |
remove selected values | with multiple
|
|
resultMaxHeight |
string |
'200px' |
change the height size of results | ||
maxResults |
number |
0 |
maximum results limit (0 = unlimited) |
||
maxResultsMessage |
string |
'Too much result…' |
message when maximum result | ||
grid |
number or string
|
option by line in grid layout (empty or 0 = no grid layout)number : item by linestring : minimal item width |
|||
listPosition |
'below' 'above' 'auto' ¹ |
'below' |
the position for the dropdown list | ¹ 'auto' : only with overlay
|
|
infiniteScroll |
boolean |
false |
active infiniteScroll on dropdown list | with ngx-infinite-scroll
|
|
infiniteScrollDistance |
number |
1.5 |
infiniteScroll distance | with ngx-infinite-scroll
|
|
infiniteScrollThrottle |
number |
150 |
infiniteScroll throttle | ||
overlay |
boolean |
false |
active an overlay mode for dropdown list (with angular cdk). (See Overlay) | ||
styleMode |
'default' 'material' 'noStyle' 'borderless'
|
'default' |
change style for material style or remove border and background color | ||
templates |
TemplateRef {option?: TemplateRef, group?: TemplateRef} etc. (see ”possible object” in Templating) |
use templates for formatting content (see Templating) | |||
templateSelection |
TemplateRef |
use templates for formatting content (see Templating) | |||
noLabelTemplate |
boolean |
false |
do not use the template in the selection, stay in text mode | ||
selectionOverride |
string or function (Select2SelectionOverride ) |
Replace selection by a textstring : %size% = total selected optionsfunction : juste show the string |
|||
selectionNoWrap |
boolean |
false |
Force selection on one line | ||
showSelectAll |
boolean |
false |
Add an option to select all options | with multiple
|
|
selectAllText |
string |
'Select all' |
Text when all options as not selected | with multiple
|
|
removeAllText |
string |
'Remove all' |
Text when all options as selected | with multiple
|
|
editPattern |
(str: string) => string |
use it for change the pattern of the filter search | |||
ngModel id required disabled readonly tabIndex
|
just like a select control |
||||
(update) |
(event: Select2UpdateEvent ) => void
|
event | triggered when user select an option | ||
(open) |
(event: Select2) => void |
event | triggered when user open the options | ||
(close) |
(event: Select2) => void |
event | triggered when user close the options | ||
(focus) |
(event: Select2) => void |
event | triggered when user enters the component | ||
(blur) |
(event: Select2) => void |
event | triggered when user leaves the component | ||
(search) |
(event: Select2SearchEvent ) => void
|
event | triggered when search text changed | with customSearchEnabled
|
|
(scroll) |
(event: Select2ScrollEvent ) => void
|
event | triggered when infiniteScroll is on up or down position |
with ngx-infinite-scroll
|
|
(removeOption) |
(event: Select2RemoveEvent ) => void
|
event | triggered when an option is removed from the list of selected options options list | with multiple
|
|
(autoCreateItem) |
(event: Select2AutoCreateEvent ) => void
|
event | triggered when a new item has been added | with autoCreate
|
@Input() selectionOverride: Select2SelectionOverride;
/** force selection on one line */
@HostBinding('class.select2-selection-nowrap')
@Input({ transform: booleanAttribute })
selectionNoWrap = false;
export interface Select2Group {
/** label of group */
label: string;
/** options list */
options: Select2Option[];
/** add classes */
classes?: string;
/** template id */
templateId?: string;
/** template data */
data?: any;
}
export interface Select2Option {
/** value */
value: Select2Value;
/** label of option */
label: string;
/** no selectable is disabled */
disabled?: boolean;
/** for identification */
id?: string;
/** add classes */
classes?: string;
/** template id */
templateId?: string;
/** template data */
data?: any;
/** hide this option */
hide?: boolean;
}
export type Select2Value = string | number | boolean | object;
export type Select2UpdateValue = Select2Value | Select2Value[];
export type Select2Data = (Select2Group | Select2Option)[];
export interface Select2UpdateEvent<U extends Select2UpdateValue = Select2Value> {
/** component */
readonly component: Select2;
/** current selected value */
readonly value: U;
/** selected option */
readonly options: Select2Option[];
}
export interface Select2AutoCreateEvent<U extends Select2UpdateValue = Select2Value> {
/** component */
readonly component: Select2;
/** current selected value */
readonly value: U;
/** selected option */
readonly options: Select2Option[];
}
export interface Select2SearchEvent<U extends Select2UpdateValue = Select2Value> {
/** component */
readonly component: Select2;
/** current selected value */
readonly value: U;
/** search text */
readonly search: string;
/** current data source */
readonly data: Select2Data;
/** method to call to update the data */
readonly filteredData: (data: Select2Data) => void;
}
export interface Select2RemoveEvent<U extends Select2UpdateValue = Select2Value> {
/** component */
readonly component: Select2;
/** current selected value */
readonly value: U;
/** remove */
readonly removedOption: Select2Option;
}
export interface Select2ScrollEvent {
/** component */
readonly component: Select2;
/** scroll way */
readonly way: 'up' | 'down';
/** search text */
readonly search: string;
/** current data */
readonly data: Select2Data;
}
export type Select2SelectionOverride = string | ((params: { size: number; options: Select2Option[] | null }) => string);
<select2 [data]="data" [templates]="template">
<ng-template #template let-data="data"><strong>{{data?.color}}</strong>: {{data?.name}}</ng-template>
</select2>
const data: Select2Data = [
{
value: 'heliotrope',
label: 'Heliotrope',
data: { color: 'white', name: 'Heliotrope' },
},
{
value: 'hibiscus',
label: 'Hibiscus',
data: { color: 'red', name: 'Hibiscus' },
},
];
<select2 [data]="data" [templates]="{option : option, group: group}">
<ng-template #option let-data="data">{{data?.name}}</ng-template>
<ng-template #group let-label="label">Group: {{label}}</ng-template>
</select2>
No difference in data structure. The template is defined by its type, option or group, automatically.
<select2 [data]="data" [templates]="{template1 : template1, template2: template2}">
<ng-template #template1 let-data="data">{{data?.name}}</ng-template>
<ng-template #template2 let-label="label" let-data="data">{{label}} : {{data?.color}}</ng-template>
</select2>
const data: Select2Data = [
{
value: 'heliotrope',
label: 'Heliotrope',
data: { color: 'white', name: 'Heliotrope' },
templateId: 'template1',
},
{
value: 'hibiscus',
label: 'Hibiscus',
data: { color: 'red', name: 'Hibiscus' },
templateId: 'template2',
},
];
TemplateRef
{template: TemplateRef}
{option?: TemplateRef, group?: TemplateRef}
{templateId1: TemplateRef, ...}
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 :
{templateSelection: TemplateRef}
{optionSelection: TemplateRef}
For group or option:
-
'id'
(from item datatemplateId
) -
'group'
or'option'
'template'
-
TemplateRef
(from html attributetemplates
) - Default render
For the selection:
-
'id'
(from item datatemplateSelectionId
) 'optionSelection'
'templateSelection'
-
TemplateRef
(from html attributetemplateSelection
) -
'id'
(from item datatemplateId
) 'option'
'template'
-
TemplateRef
(from html attributetemplates
) - Default render
If the overlay mode is used / activated, add to the project root in CSS (with ViewEncapsulation.None
)
@import '~@angular/cdk/overlay-prebuilt.css';
It's possible to change different colors (and more) with CSS variables without having to modify them with ::ng-deep
or other CSS rules :
:root {
/* size */
--select2-single-height: 28px;
--select2-multiple-height: 28px;
/* label */
--select2-label-text-color: #000;
--select2-required-color: red;
/* selection */
--select2-selection-border-radius: 4px;
--select2-selection-background: #fff;
--select2-selection-disabled-background: #eee;
--select2-selection-border-color: #aaa;
--select2-selection-focus-border-color: #000;
--select2-selection-text-color: #111;
--select2-selection-line-height: 28px;
--select2-selection-padding: 0 0 0 8px;
/* selection (multiple) */
--select2-selection-multiple-gap: 2px 5px;
--select2-selection-multiple-padding: 2px 5px;
/* selection: choice item (multiple) */
--select2-selection-choice-background: #e4e4e4;
--select2-selection-choice-text-color: #000;
--select2-selection-choice-border-color: #aaa;
--select2-selection-choice-close-color: #999;
--select2-selection-choice-hover-close-color: #333;
/* placeholder */
--select2-placeholder-color: #999;
--select2-placeholder-overflow: ellipsis;
/* no result message */
--select2-no-result-color: #888;
--select2-no-result-font-style: italic;
/* no result message */
--select2-too-much-result-color: #888;
--select2-too-much-result-style: italic;
/* reset */
--select2-reset-color: #999;
/* arrow */
--select2-arrow-color: #888;
/* dropdown panel */
--select2-dropdown-background: #fff;
--select2-dropdown-border-color: #aaa;
--select2-dropdown-above-border-bottom: none;
--select2-dropdown-above-border-bottom-left-radius: 0;
--select2-dropdown-above-border-bottom-right-radius: 0;
--select2-dropdown-below-border-top: none;
--select2-dropdown-below-border-top-left-radius: 0;
--select2-dropdown-below-border-top-right-radius: 0;
/* overlay */
--select2-overlay-backdrop: transparent;
/* search field */
--select2-search-border-color: #aaa;
--select2-search-background: #fff;
--select2-search-border-radius: 0px;
/* dropdown option */
--select2-option-text-color: #000;
--select2-option-disabled-text-color: #999;
--select2-option-disabled-background: transparent;
--select2-option-selected-text-color: #000;
--select2-option-selected-background: #ddd;
--select2-option-highlighted-text-color: #fff;
--select2-option-highlighted-background: #5897fb;
--select2-option-group-text-color: gray;
--select2-option-group-background: transparent;
--select2-option-padding: 6px;
/* hint */
--select2-hint-text-color: #888;
/* for Material ------------------------------------------*/
--select2-material-underline: #ddd;
--select2-material-underline-active: #5a419e;
--select2-material-underline-disabled: linear-gradient(
to right,
rgba(0, 0, 0, 0.26) 0,
rgba(0, 0, 0, 0.26) 33%,
transparent 0
);
--select2-material-underline-invalid: red;
--select2-material-placeholder-color: rgba(0, 0, 0, 0.38);
--select2-material-selection-background: #ddd;
--select2-material-option-selected-background: rgba(0, 0, 0, 0.04);
--select2-material-option-highlighted-text-color: #000;
--select2-material-option-selected-text-color: #ff5722;
}
npm run build:lib
npm run publish:lib
npm run build:demo
Like Angular, this module is released under the permissive MIT license. Your contributions are always welcome.