Nepotistic Pontifex Maximus

    ng-select2-component
    TypeScript icon, indicating that this package has built-in type declarations

    10.0.0 • Public • Published

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

      • ngx-infinite-scroll@^14.0.0

    Note:
    For angular 7, 8 and 9 : 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 and more (Ivy) : use version 10.0.0.

    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
    maxResults number 0 maximum results limit (0 = unlimited)s
    maxResultsMessage string 'Too much result…' message when maximum result
    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
    infiniteScrollThrottle number 150 infiniteScroll throttle
    overlay boolean false active an overlay mode for dropdown list (with angular cdk). (See Overlay)
    styleMode '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-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;
    
        /* 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
    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.

    Install

    npm i ng-select2-component

    DownloadsWeekly Downloads

    2,021

    Version

    10.0.0

    License

    MIT

    Unpacked Size

    703 kB

    Total Files

    36

    Last publish

    Collaborators

    • zefling