ng-awesome-select

ng-awesome-select is a customizable Angular dropdown component designed to enhance user interaction in forms. It supports single and multiple selections, searching, and custom item templates.

Table of Contents

• Installation
• Usage
• API Reference
• Customization
• Examples
• Contributing
• License

Installation

To install the ng-awesome-select library, run the following command:

npm install ng-awesome-select

Usage

To use the ng-awesome-select component in your Angular application:

1. Import the Component: Add the component to your module:

   import { NgAwesomeSelectComponent } from 'ng-awesome-select';
   
   @NgModule({
     declarations: [AppComponent],
     imports: [CommonModule, FormsModule, NgAwesomeSelectComponent],
     bootstrap: [AppComponent]
   })
   export class AppModule {}

2. Add the Component in Template: Use the component in your template with the necessary inputs and outputs:

   <ng-awesome-select 
       [items]="myItems" 
       [placeholder]="'Select an item'" 
       [bindLabel]="'name'" 
       [bindValue]="'id'" 
       [searchable]="true" 
       (change)="onSelectionChange($event)">
   </ng-awesome-select>

API Reference

Inputs

| Input | Type | Description | |----------------------|---------------------|------------------------------------------------------------------------- | | items | any[] | The list of items to display in the dropdown. | | placeholder | string | Placeholder text when no item is selected. | | bindLabel | string | Key name for the item label. | | bindValue | string | Key name for the item value. | | bindImg | string | Key name for the item image (if applicable). | | notFoundText | string | Text to display when no items are found. | | disabled | boolean | Whether the dropdown is disabled. | | multiple | boolean | Whether the dropdown allows multiple selection. | | maxHeight | string | Maximum height of the dropdown (default: 200px). | | loading | boolean | Loading state for displaying while data is being fetched. | | searchable | boolean | Whether the dropdown is searchable (default: true). | | clearable | boolean | Whether the dropdown selection can be cleared (default: false). | | isShowSeeAll | boolean | Whether to show a 'See All' option when applicable. | | itemTemplate | TemplateRef<any> | Template for rendering items (if required). |

Outputs

| Output | Type | Description | |-------------------------|---------------------|------------------------------------------------------------------------| | change | EventEmitter<any> | Emits the selected item when an item is selected. | | selectedItemChange | EventEmitter<any> | Emits the current selected item. | | searchResultItems | EventEmitter<any> | Emits the filtered items based on the search term. | | seeAllSelected | EventEmitter<any> | Emits when the 'See All' option is selected. |

Customization

You can customize the appearance of the dropdown by modifying the styles in the component. The CSS variables used in the component can be overridden in your global styles.

CSS Variables

You can modify the following CSS variables in your global styles:

• --Border-Neutral-Primary-Default
• --Bg-Neutral-Primary-Default
• --Component-Select-Border-Select-Default
• --Spacing-1
• --Size-XL

Examples

Basic Example

<ng-awesome-select 
    [items]="[{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }]" 
    [placeholder]="'Select an item'" 
    [bindLabel]="'name'" 
    [bindValue]="'id'" 
    (change)="onSelectionChange($event)">
</ng-awesome-select>

Searchable Dropdown

<ng-awesome-select 
    [items]="myItems" 
    [placeholder]="'Search...'" 
    [searchable]="true" 
    (change)="onSelectionChange($event)">
</ng-awesome-select>

Contributing

Contributions are welcome! Please submit a pull request or create an issue for any suggestions or improvements.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Notes:

• Make sure to include a LICENSE file in your project repository that matches the licensing information in the README.
• Adjust any content as needed to fit your specific project requirements or updates.
• This README structure provides clarity and organization, making it easy for users to understand and utilize your component.