ng-select2-component

Select2

This Angular CLI module it's a fork of select2-component without Vue & React. For Vue or React, please use the original component.

Installation

npm i ng-select2-component --save

Requirements

• peerDependencies:

  • angular 10.0.0 and more
  • angular/cdk 10.0.0 and more

• dependencies (include):

  • ngx-infinite-scroll@^10.0.1

Note:
For angular 7, 8 and 9 : use version 7.3.1.

Demo

See a demo.

Features

• select one
• options or groups
• scroll
• local search
• select by keyboard
• disabled option
• disabled component
• hide search box
• placeholder
• multiple selection
• material style
• form binding
• templating

Usage

example

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>

properties and events of the component

name	type	status	default	description
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 with multiple)
limitSelection	number		0	to limit multiple selection (0 = unlimited)
hideSelectedItems	boolean		false	for multiple, remove selected values
resultMaxHeight	string		'200px'	change the height size of results
listPosition	'below' 'above'		'below'	the position for the dropdown list
infiniteScroll	boolean		false	active infiniteScroll on dropdown list ( with ngx-infinite-scroll)
infiniteScrollDistance	number		1.5	infiniteScroll distance
infiniteScrollThrottle	number		150	infiniteScroll throttle
overlay	boolean		false	active an overlay mode for dropdown list (with angular cdk). (See Overlay)
sytleMode	'default' 'material' 'noStyle'		'default'	change style for material style or remove border and background color
templates	TemplateRef {option?: TemplateRef, group?: TemplateRef} {templateId1: TemplateRef, ...}			use templates for formatting content (see Templating)
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
(scroll)	(event: Select2ScrollEvent) => void	event		triggered when infiniteScroll is on up or down position
(removedOption)	(event: Select2RemoveEvent) => void	event		for multiple, triggered when an option is removed from the list of selected options options list

select2 data structure

type Select2Data = (Select2Group | Select2Option)[];

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;
}

type Select2Value = string | number | boolean | object;

type Select2UpdateValue = Select2Value | Select2Value[];

export interface Select2UpdateEvent<U extends Select2UpdateValue = Select2Value> {
    component: Select2;
    value: U;
    options: Select2Option[];
}

export interface Select2SearchEvent<U extends Select2UpdateValue = Select2Value> {
    component: Select2;
    value: U;
    search: string;
}

export interface Select2RemoveEvent<U extends Select2UpdateValue = Select2Value> {
    component: Select2;
    value: U;
    removedOption: Select2Option;
}

export interface Select2ScrollEvent {
    component: Select2;
    way: 'up' | 'down';
    search: string;
}

Templating

Unique template

<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' }
    }
]

Template group & option

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

Template by templateId

<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'
    }
]

Overlay

If the overlay mode is used / activated, add to the project root in CSS (with ViewEncapsulation.None)

@import "~@angular/cdk/overlay-prebuilt.css";

CSS variables (doesn't work on IE11)

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 {
    /* 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: #444;

    /* 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-font-style-color: italic;

    /* reset */
    --select2-reset-color: #999;

    /* arrow */
    --select2-arrow-color: #888;

    /* dropdown panel */
    --select2-dropdown-background: #fff;
    --select2-dropdown-border-color: #aaa;

    /* 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;

    /* 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;
}

For IE11, see css-vars-ponyfill.

Publishing the library

npm run build:lib
cd dist/ng-select2-component
npm publish

Update Demo

npm run build:demo

License

Like Angular, this module is released under the permissive MIT license. Your contributions are always welcome.

Changelog

V8.0.0 (2021-06-30)

Breaking Changes

• minimum required support has been upgraded to Angular 10.0.
• remove parameters material and noStyle, use styleMode.

Changes

• add overlay parameter with Angular CDK, to change the display method of the dropdown list to the root of the DOM. (See README).
• add noResultMessage parameter, to display a message if there is no result.
• add styleMode parameter, to choose an alternative predefined style of the component.