ngx-choices.js

Angular Choices

A lightweight wrapper for the awesome choices.js library
Explore the configuration options »

View Example App - View Demo · Report Bug · Request Feature

Installation

With NPM:

npm install ngx-choices.js

With Yarn:

yarn add ngx-choices.js

Stylesheet

To style your choices you can either use the original stylesheet from choices.js or the one from this repository. Both are equivalent, but this one has a shorter path :^)

With angular.json:

"architect": {
  "build": {
    ...,
    "styles": [
      "node-modules/ngx-choices/styles/ngx-choices.scss"
    ],
    ...,
  }
}

With scss:

@import "node_modules/ngx-choices/styles/ngx-choices";

Usage

Include the NgxChoicesModule in your AppModule. This will use the default configuration as described in the choices.js documentation.

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, NgxChoicesModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

To configure the library globally use the forRoot pattern. This will override the defaults as described in the choices.js documentation.

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    NgxChoicesModule.forRoot({
      allowHTML: true,
    }),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

If you want to silence the warning from choices.js about allowHTML, set it globally as shown above to either true or false.

Instantiate Component

To create a text input:

<input type="text" ngxChoice />

To create a single-choice input:

<select [choices]="choices" ngxChoice></select>

To create a multiple-choice input:

<select [choices]="choices" multiple ngxChoice></select>

Customization & Updates

To customize a single ngx-choice bind the wanted input to the directive. Doing so overrides the default configuration of choices.js and the ones given by the forRoot pattern. In the following example we add an icon to all options using the removeItemButton input.

<select
  [choices]="choices"
  [removeItemButton]="true"
  multiple
  ngxChoice
></select>

For the example above create a property choices on the component containing all possible choices.

public choices = [
  {
    value: 'Option 1',
    label: 'Option 1',
    selected: true,
    disabled: false,
  },
  {
    value: 'Option 2',
    label: 'Option 2',
    selected: false,
    disabled: false,
    customProperties: {
      description: 'Custom description about Option 2',
      random: 'Another random custom property',
    },
  },
];

To receive events from the component subscribe to them in the usual angular way:

<select
  [choices]="choices"
  (showDropdown)="showDropdown"
  ngxChoice
></select>

To find a list of all possible inputs and outputs see the official documentation from choices.js.

Forms

To bind the directive to an angular form add the [formControl] property, just like with a native form component.

<select
  [choices]="choices"
  [formControl]="control"
  ngxChoice
></select>

And add the control property to the component.

public control = new FormControl('Option 2');

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.