Native UI Select Angular component (demo)

ngx-select-ex

Native Angular component for Select

• Requires Angular version 18 or higher!
• Compatible with Bootstrap 3 and Bootstrap 4

Usage

1. Install ngx-select-ex through npm package manager using the following command:

   npm i ngx-select-ex --save

2. Add NgxSelectModule into your AppModule class. app.module.ts would look like this:

   import {NgModule} from '@angular/core';
   import {BrowserModule} from '@angular/platform-browser';
   import {AppComponent} from './app.component';
   import { NgxSelectModule } from 'ngx-select-ex';
   
   @NgModule({
     imports: [BrowserModule, NgxSelectModule],
     declarations: [AppComponent],
     bootstrap: [AppComponent],
   })
   export class AppModule {
   }

   If you want to change the default options then use next code:

   import {NgModule} from '@angular/core';
   import {BrowserModule} from '@angular/platform-browser';
   import {AppComponent} from './app.component';
   import { NgxSelectModule, INgxSelectOptions } from 'ngx-select-ex';
   
   const CustomSelectOptions: INgxSelectOptions = { // Check the interface for more options
       optionValueField: 'id',
       optionTextField: 'name'
   };
   
   @NgModule({
     imports: [BrowserModule, NgxSelectModule.forRoot(CustomSelectOptions)],
     declarations: [AppComponent],
     bootstrap: [AppComponent],
   })
   export class AppModule {
   }

3. Include Bootstrap styles. For example add to your index.html

   <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">

4. Add the tag <ngx-select> into some html

   <ngx-select [items]="items" [(ngModel)]="itemId"></ngx-select>

5. More information regarding of using ngx-select-ex is located in demo.

API

Any item can be disabled for prevent selection. For disable an item add the property disabled to the item.

Warning! Although the component contains the select and the remove events, the better solution is using valueChanges of the FormControl.

import {Component} from '@angular/core';
import {FormControl} from '@angular/forms';

@Component({
    selector: 'app-example',
    template: `<ngx-select [items]="['111', '222']" [formControl]="selectControl"></ngx-select>`
})
class ExampleComponent {
    public selectControl = new FormControl();

    constructor() {
        this.selectControl.valueChanges.subscribe(value => console.log(value));
    }
}

Styles and customization

Currently, the component contains CSS classes named within BEM Methodology. As well it contains the "Bootstrap classes". Recommended use BEM classes for style customization.

List of styles for customization:

• ngx-select - Main class of the component.
• ngx-select_multiple - Modifier of the multiple mode. It's available when the property multiple is true.
• ngx-select__disabled - Layer for the disabled mode.
• ngx-select__selected - The common container for displaying selected items.
• ngx-select__toggle - The toggle for single mode. It's available when the property multiple is false.
• ngx-select__placeholder - The placeholder item. It's available when the property multiple is false.
• ngx-select__selected-single - The selected item with single mode. It's available when the property multiple is false.
• ngx-select__selected-plural - The multiple selected item. It's available when the property multiple is true.
• ngx-select__allow-clear - The indicator that the selected single item can be removed. It's available while properties the multiple is false and the allowClear is true.
• ngx-select__toggle-buttons - The container of buttons such as the clear and the toggle.
• ngx-select__toggle-caret - The drop-down button of the single mode. It's available when the property multiple is false.
• ngx-select__clear - The button clear.
• ngx-select__clear-icon - The cross icon.
• ngx-select__search - The input field for full text lives searching.
• ngx-select__choices - The common container of items.
• ngx-select__item-group - The group of items.
• ngx-select__item - An item.
• ngx-select__item_disabled - Modifier of a disabled item.
• ngx-select__item_active - Modifier of the activated item.

Templates

For extended rendering customisation you are can use the ng-template:

<ngx-select [items]="items" optionValueField="hex" optionTextField="name" [(ngModel)]="ngxValue">

    <ng-template ngx-select-option-selected let-option let-text="text">
        <span class="color-box" [style]="style('background-color:' + option.value)"></span>
        <span [innerHtml]="text"></span>
        ({{option.data.hex}})
    </ng-template>

    <ng-template ngx-select-option let-option let-text="text">
        <span class="color-box" [style]="style('background-color:' + option.value)"></span>
        <span [innerHtml]="text"></span>
        ({{option.data.hex}})
    </ng-template>

    <ng-template ngx-select-option-not-found>
        Nothing found
    </ng-template>

</ngx-select>

Also, you are can mix directives for reducing template:

<ngx-select [items]="items" optionValueField="hex" optionTextField="name" [(ngModel)]="ngxValue">
    <ng-template ngx-select-option-selected ngx-select-option let-option let-text="text">
        <span class="color-box" [style]="style('background-color:' + option.value)"></span>
        <span [innerHtml]="text"></span>
        ({{option.data.hex}})
    </ng-template>

    <ng-template ngx-select-option-not-found let-input>
        Not found <button (click)="addItem(input)">(+) Add "{{input}}" as new item</button>
    </ng-template>
</ngx-select>

Description details of the directives:

1. ngx-select-option-selected - Customization rendering selected options. Representing variables:
   • option (implicit) - object of type INgxSelectOption.
   • text - The text defined by the property optionTextField.
   • index - Number value of index the option in the select list. Always equal to zero for the single select.
2. ngx-select-option - Customization rendering options in the dropdown menu. Representing variables:
   • option (implicit) - object of type INgxSelectOption.
   • text - The highlighted text defined by the property optionTextField. It is highlighted in the search.
   • index - Number value of index for the top level.
   • subIndex - Number value of index for the second level.
3. ngx-select-option-not-found - Customization "not found text". Does not represent any variables.

Troubleshooting

Please follow this guidelines when reporting bugs and feature requests:

1. Use GitHub Issues board to report bugs and feature requests (not our email address)
2. Please always write steps to reproduce the error. That way we can focus on fixing the bug, not scratching our heads trying to reproduce it.

Thanks for understanding!

Contribute

Start working:

• npm install
• npm run build:package - NECESSARY since DEMO uses the package from ./dist folder!

Other commands:

• npm start - Run demo for local debugging.
• npm test - Run unit tests only once. Use ng test for running tests with files watching.
• npm run build - Build the demo & package for release & publishing.

After build you will be able:

• Install the component to another project by npm install /path/to/ngx-select-ex/dist.
• Link another project to the component npm link /path/to/ngx-select-ex/dist. Warning! Then use the flag --preserve-symlinks

Do not forget make a pull request to the ngx-select-ex

License

The MIT License (see the LICENSE file for the full text)