BugSplat

Crash and error reporting built for busy developers.

👋 Introduction

BugSplat's @bugsplat/ngb-filterable-dropdown package provides a powerful dropdown control for complicated filtering. Take a peek our example that demonstrates how to filter and select various items in a collection.

🏗 Installation

Install @bugsplat/ngb-filterable-dropdown and the associated peer dependencies @ng-bootstrap/ng-bootstrap and Bootstrap:

npm i @bugsplat/ngb-filterable-dropdown @ng-bootstrap/ng-bootstrap bootstrap

🏃 Usage

Add NgbFilterableDropdownModule to your NgModule imports for each module where you plan to use the filterable dropdown:

import { NgbFilterableDropdownModule } from '@bugsplat/ngb-filterable-dropdown'

@NgModule({
  ...
  imports: [
    NgbFilterableDropdownModule
  ],
  ...
})

Add ngb-filterable-dropdown to your component's template:

<ngb-filterable-dropdown
  [allowCreateItem]="allowCreateItem"
  [autoClose]="autoClose"
  [items]="items"
  [disabled]="disabled"
  [placeholder]="placeholder"
  [searchInputPlaceholder]="searchInputPlaceholder"
  [selection]="selection"
  [selectionMode]="selectionMode"
  (itemCreated)="onItemCreated($event)"
  (openChanged)="onOpenChanged($event)"
  (selectionChanged)="onSelectionChanged($event)"
>
</ngb-filterable-dropdown>

The items input accepts either an array of strings or an array of objects with optional badge configuration. See the Item Badges section for details on using badges.

🧩 API

Customize your dropdown by leveraging the inputs and outputs of @bugsplat/ngb-filterable-dropdown as described below.

Selection

The component takes two main inputs, a list of items that are selectable and a sub-list of strings that are already selected.

Items can be provided as simple strings for basic usage:

items: Array<string> = ['Beetle', 'Ant', 'Moth', 'Fire Ant', 'Dung Beetle', 'Grass Ant'];
selection: Array<string> = ['Moth'];

Or as objects with optional badge configuration for advanced usage:

import { DropdownItemInput } from '@bugsplat/ngb-filterable-dropdown';

items: Array<DropdownItemInput> = [
  { value: 'Admin User', badge: { text: 'ADMIN', backgroundColor: '#e9ecef', textColor: '#6c757d' } },
  'Regular User',
  { value: 'Guest User', badge: { text: 'GUEST' } }
];
selection: Array<string> = ['Admin User'];

Item Badges

You can add visual badges to dropdown items by using the object format. Badges support full customization:

interface DropdownItemBadge {
  text: string;                  // Badge text (required)
  backgroundColor?: string;       // Background color (default: #e9ecef)
  textColor?: string;            // Text color (default: #6c757d)
  borderColor?: string;          // Border color (optional)
  cssClass?: string;             // Custom CSS class for full control (optional)
}

interface DropdownItem {
  value: string;                 // The item value
  badge?: DropdownItemBadge;     // Optional badge configuration
}

type DropdownItemInput = string | DropdownItem;

Example with different badge styles:

items: Array<DropdownItemInput> = [
  // With custom colors
  { 
    value: 'Production', 
    badge: { 
      text: 'PROD', 
      backgroundColor: '#dc3545', 
      textColor: '#ffffff' 
    } 
  },
  // With default styling
  { 
    value: 'Staging', 
    badge: { text: 'STAGING' } 
  },
  // No badge
  'Development',
  // With custom CSS class
  { 
    value: 'Admin Only', 
    badge: { 
      text: 'ADMIN', 
      cssClass: 'my-custom-badge-class' 
    } 
  }
];

Badges are displayed only in the dropdown list, not in the toggle button when selected. The items input maintains full backward compatibility - you can mix strings and objects in the same array.

Selection Modes

You can also specify whether or not to allow multiple items to be selected. By default, the component allows one item to be selected.

selectionMode: NgbFilterableDropdownSelectionMode =
  NgbFilterableDropdownSelectionMode.SingleSelect;

Create New Items

You can specify whether or not to allow new items to be created. By default, the component does not allow new items to be created.

allowCreateItem: boolean = false;

Opening and Closing

The open/close behavior of the dialog can be changed by setting autoClose to true or false. Alternatively you can specify whether to close on an outside or inside click.

autoClose: boolean | 'inside' | 'outside' = false;

Disabling

Dropdowns can be disabled at any time by setting disabled to true.

disabled: boolean = false;

Loading

You can also display a loading placeholder by setting loading to true.

loading: boolean = false;

Placeholders

If you'd like to specify the placeholder in the search input you can set the value of searchInputPlaceholder to a string of your choosing.

placeholder: string = 'No Items Selected';
searchInputPlaceholder: string = 'Search';

Outputs

The component provides the selected data back to the parent through the selectionChanged event.

onSelectionChanged(event: SelectionChangedEvent) {
  const selection = event.selection;
}

When an item is created the component outputs an event with the properties created, items, and selection.

onItemCreated(event: ItemCreatedEvent) {
  const created = event.created;
  const selection = event.selection;
  const items = event.items;
}

The component also provides an event when the dropdown is opened or closed through the openChanged event.

onOpenChanged(event: OpenChangedEvent) {
  const open = event.open;
}

🐛 About

@bugsplat/ngb-filterable-dropdown is an open source library developed by BugSplat! BugSplat is a crash and error reporting tool used by developers to find, fix, and track errors in their applications.

If you're interested in error reporting, check out our Angular integration.

With :heart:
BugSplat