Skip to content

Harvest-Dev/ng-select2

Repository files navigation

npm version Downloads GitHub license

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 18.0.0 and more
    • angular/cdk 18.0.0 and more
  • dependencies (include):

    • ngx-infinite-scroll 18.0.0 and more

Note:

  • For angular 7, 8 and 9 (View Engine): use version 7.3.1.
  • For angular 10, 11 and 12 (View Engine): use version 8.1.0.
  • For angular 13 (Ivy): use version 9.0.0.
  • For angular 14 (Ivy): use version 10.0.0.
  • For angular 15 (Ivy): use version 11.1.0.
  • For angular 16 (Ivy): use version 12.1.0.
  • For angular 16.1 (Ivy): use version 13.0.10.
  • For angular 17 (Ivy): use version 14.0.1.
  • For angular 18 and more (Ivy): use version 15.0.1.

Demo

See a demo.

Features

  • 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

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 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 line
string: 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
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

select2 data structure

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

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

Possible object

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

Priority order

For group or option:

  • 'id' (from item data templateId)
  • 'group' or 'option'
  • 'template'
  • TemplateRef (from html attribute templates)
  • Default render

For the selection:

  • 'id' (from item data templateSelectionId)
  • 'optionSelection'
  • 'templateSelection'
  • TemplateRef (from html attribute templateSelection)
  • 'id' (from item data templateId)
  • 'option'
  • 'template'
  • TemplateRef (from html attribute templates)
  • Default render

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

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

Publishing the library

npm run build:lib
npm run publish:lib

Update Demo

npm run build:demo

License

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