Socket
Socket
Sign inDemoInstall

ng-select2-component

Package Overview
Dependencies
Maintainers
0
Versions
63
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

ng-select2-component

An Angular select2 component.


Version published
Weekly downloads
5.2K
decreased by-12.77%
Maintainers
0
Weekly downloads
 
Created
Source

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

nametypestatusdefaultdescriptionrequired
dataSelect2Datarequiredthe data of the select2
valueSelect2Valueinitial value
minCharForSearchnumber0start the search when the number of characters is reached (0 = unlimited)
minCountForSearchnumber6hide search box if options.length < minCountForSearch
displaySearchStatus'default'
'hidden'
'always'
'default'display the search box (default : is based on minCountForSearch)
placeholderstringthe placeholder string if nothing selected
noResultMessagestringthe message string if no results when using the search field
customSearchEnabledbooleanfalsewill trigger search event, and disable inside filter
multiplebooleanfalseselect multiple options
resettablebooleanfalseadd a button to reset valuenot multiple
resetSelectedValueanyundefinedselected option when × is clickednot multiple and with resettable
autoCreatebooleanfalsegives the possibility to add elements not present in the list.
limitSelectionnumber0to limit multiple selection (0 = unlimited)
hideSelectedItemsbooleanfalseremove selected valueswith multiple
resultMaxHeightstring'200px'change the height size of results
maxResultsnumber0maximum results limit (0 = unlimited)
maxResultsMessagestring'Too much result…'message when maximum result
gridnumber or stringoption 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
infiniteScrollbooleanfalseactive infiniteScroll on dropdown listwith ngx-infinite-scroll
infiniteScrollDistancenumber1.5infiniteScroll distancewith ngx-infinite-scroll
infiniteScrollThrottlenumber150infiniteScroll throttle
overlaybooleanfalseactive 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
templatesTemplateRef
{option?: TemplateRef, group?: TemplateRef}
etc.
(see ”possible object” in Templating)
use templates for formatting content (see Templating)
templateSelectionTemplateRefuse templates for formatting content (see Templating)
noLabelTemplatebooleanfalsedo not use the template in the selection, stay in text mode
editPattern(str: string) => stringuse it for change the pattern of the filter search
ngModel
id
required
disabled
readonly
tabIndex
just like a select control
(update)(event: Select2UpdateEvent) => voideventtriggered when user select an option
(open)(event: Select2) => voideventtriggered when user open the options
(close)(event: Select2) => voideventtriggered when user close the options
(focus)(event: Select2) => voideventtriggered when user enters the component
(blur)(event: Select2) => voideventtriggered when user leaves the component
(search)(event: Select2SearchEvent) => voideventtriggered when search text changedwith customSearchEnabled
(scroll)(event: Select2ScrollEvent) => voideventtriggered when infiniteScroll is on up or down positionwith ngx-infinite-scroll
(removeOption)(event: Select2RemoveEvent) => voideventtriggered when an option is removed from the list of selected options options listwith multiple
(autoCreateItem)(event: Select2AutoCreateEvent) => voideventtriggered when a new item has been addedwith 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.

Keywords

FAQs

Package last updated on 21 Aug 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc