Angular ngx-select-v1 - Lightweight all in one UI Select, Multiselect and Autocomplete

See Demos or try in Stackblitz or Plunker

Table of contents

• Features
• Getting started
• API
• Change detection
• Custom styles
  • Validation state
• Contributing
• Development
• Inspiration

Features

• [x] Custom binding to property or object
• [x] Custom option, label, header and footer templates
• [x] Virtual Scroll support with large data sets (>5000 items).
• [x] Infinite scroll
• [x] Keyboard navigation
• [x] Multiselect
• [x] Flexible autocomplete with client/server filtering
• [x] Custom search
• [x] Custom tags
• [x] Append to
• [x] Group items
• [x] Output events
• [x] Accessibility
• [x] Good base functionality test coverage
• [x] Themes

Warning

Library is under active development and may have API breaking changes for subsequent major versions after 1.0.0.

Getting started

Step 1: Install ngx-select-v1:

NPM

npm install --save @ngx-select-v1/ngx-select-v1

YARN

yarn add @ngx-select-v1/ngx-select-v1

Step 2: Import the NgxSelectV1Module and angular FormsModule module:

import { NgxSelectV1Module } from "@ngx-select-v1/ngx-select-v1";
import { FormsModule } from "@angular/forms";

@NgModule({
  declarations: [AppComponent],
  imports: [NgxSelectV1Module, FormsModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

Step 3: Include a theme:

To allow customization and theming, ngx-select-v1 bundle includes only generic styles that are necessary for correct layout and positioning. To get full look of the control, include one of the themes in your application. If you're using the Angular CLI, you can add this to your styles.scss or include it in angular-cli.json.

@import "~@ngx-select-v1/ngx-select-v1/themes/default.theme.css";
// ... or
@import "~@ngx-select-v1/ngx-select-v1/themes/material.theme.css";

Step 4 (Optional): Configuration

You can also set global configuration and localization messages by providing custom NG_SELECT_DEFAULT_CONFIG

providers: [
  {
    provide: NG_SELECT_DEFAULT_CONFIG,
    useValue: {
      notFoundText: "Custom not found",
    },
  },
];

SystemJS

If you are using SystemJS, you should also adjust your configuration to point to the UMD bundle.

In your systemjs config file, map needs to tell the System loader where to look for ngx-select-v1:

map: {
  '@ngx-select-v1/ngx-select-v1': 'node_modules/@ngx-select-v1/ngx-select-v1/bundles/ngx-select-v1.umd.js',
}

API

Inputs

Outputs

Methods

Other

Change Detection

ngx-select-v1 component implements OnPush change detection which means the dirty checking checks for immutable data types. That means if you do object mutations like:

this.items.push({ id: 1, name: "New item" });

Component will not detect a change. Instead you need to do:

this.items = [...this.items, { id: 1, name: "New item" }];

This will cause the component to detect the change and update. Some might have concerns that this is a pricey operation, however, it is much more performant than running ngDoCheck and constantly diffing the array.

Custom styles

If you are not happy with default styles you can easily override them with increased selector specificity or creating your own theme. E.g.

<ngx-select-v1 class="custom"></ngx-select-v1>

.ngx-select-v1.custom {
  border: 0px;
  min-height: 0px;
  border-radius: 0;
}
.ngx-select-v1.custom .ngx-select-v1-container {
  min-height: 0px;
  border-radius: 0;
}

Validation state

By default when you use reactive forms validators or template driven forms validators css class ng-invalid will be applied on ngx-select-v1. You can show errors state by adding custom css style

ngx-select-v1.ng-invalid.ng-touched .ngx-select-v1-container {
  border-color: #dc3545;
  box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075), 0 0 0 3px #fde6e8;
}

Contributing

Contributions are welcome. You can start by looking at issues with label Help wanted or creating new Issue with proposal or bug report. Note that we are using https://conventionalcommits.org/ commits format.

Development

Perform the clone-to-launch steps with these terminal commands.

Run demo page in watch mode

git clone https://github.com/ngx-select-v1/ngx-select-v1
cd ngx-select-v1
yarn
yarn run start

Testing

yarn run test
or
yarn run test:watch

Release

To release to npm just run ./release.sh, of course if you have permissions ;)

Inspiration

This component is inspired by React select and Vitual scroll. Check theirs amazing work and components :)