Twitter2.3k

Combobox

An input combined with a list of predefined items to select.

Installation

ng g @spartan-ng/cli:ui combobox

Usage

import { BrnPopoverContent } from '@spartan-ng/brain/popover';
import { HlmComboboxImports } from '@spartan-ng/helm/combobox';
<hlm-combobox>
  <hlm-combobox-input placeholder="Select a framework"></hlm-combobox-input>
  <div *brnPopoverContent hlmComboboxContent>
    <hlm-combobox-empty>No items found.</hlm-combobox-empty>
    <div hlmComboboxList>
      @for (framework of frameworks; track $index) {
      	<hlm-combobox-item [value]="framework">{{ framework.label }}</hlm-combobox-item>
      }
    </div>
  </div>
</hlm-combobox>

Configuration

The combobox can be configured via provideBrnComboboxConfig or by passing the individual config as input. This is the default combobox config: 

import { comboboxContainsFilter, provideBrnComboboxConfig } from '@spartan-ng/brain/combobox';

provideBrnComboboxConfig({
	filterOptions: {
		usage: 'search',
		sensitivity: 'base',
		ignorePunctuation: true,
	},
	filter: (itemValue: T, search: string, collator: Intl.Collator, itemToString?: ComboboxItemToString<T>) =>
		comboboxContainsFilter(itemValue, search, collator, itemToString),
	isItemEqualToValue: (itemValue: T, selectedValue: T | null) => Object.is(itemValue, selectedValue),
	itemToString: undefined,
});

Filter

The combobox matches items using Intl.Collator for robust string comparison. The filterOptions accepts all Intl.CollatorOptions , plus a locale .

The default filter implementation uses a comboboxContainsFilter to check if the item value contains the search string. Provide a custom filter function for other filtering behavior.

Built-in combobox filters are:

  • comboboxContainsFilter - Returns true if the item value contains the search string.
  • comboboxStartsWithFilter - Returns true if the item value starts with the search string.
  • comboboxEndsWithFilter - Returns true if the item value ends with the search string.

Objects

The combobox works out of the box with string values and objects in the shape of { label: string; value: string; } , the label (1) or the value (2) will be used automatically. For other object shapes provide a custom itemToString function to extract the label from the object.

Provide a custom isItemEqualToValue function to determine if a combobox item value matches the current selected value. Defaults to Object.is comparison.

Examples

With Clear Button

Disabled

With Groups

With Groups and Separators

With Icon Addon

Popup

Form

Multiple

Angular

Multiple Disabled

AnalogAstro

Multiple Form

Analog

Brain API

BrnComboboxAnchor

Selector: [brnComboboxAnchor]

BrnComboboxChipInput

Selector: input[brnComboboxChipInput]

Inputs

PropTypeDefaultDescription
id string `brn-combobox-input-${++BrnComboboxChipInput._id}` The id of the combobox input

BrnComboboxChipRemove

Selector: button[brnComboboxChipRemove]

BrnComboboxChip

Selector: [brnComboboxChip]

Inputs

PropTypeDefaultDescription
value* (required) T --

BrnComboboxClear

Selector: [brnComboboxClear]

BrnComboboxContent

Selector: [brnComboboxContent]

BrnComboboxEmpty

Selector: [brnComboboxEmpty]

BrnComboboxGroup

Selector: [brnComboboxGroup]

BrnComboboxInputWrapper

Selector: [brnComboboxInputWrapper]

BrnComboboxInput

Selector: input[brnComboboxInput]

ExportAs: brnComboboxInput

Inputs

PropTypeDefaultDescription
id string `brn-combobox-input-${++BrnComboboxInput._id}` The id of the combobox input

BrnComboboxItem

Selector: [brnComboboxItem]

Inputs

PropTypeDefaultDescription
id string `brn-combobox-item-${++BrnComboboxItem._id}` A unique id for the item
value* (required) T - The value this item represents.
disabled boolean false -

BrnComboboxLabel

Selector: [brnComboboxLabel]

Inputs

PropTypeDefaultDescription
id string `brn-combobox-label-${++BrnComboboxLabel._id}` The id of the combobox label

BrnComboboxList

Selector: [brnComboboxList]

Inputs

PropTypeDefaultDescription
id string `brn-combobox-list-${++BrnComboboxList._id}` The id of the combobox list

BrnComboboxMultiple

Selector: [brnCombobox]

Inputs

PropTypeDefaultDescription
disabled boolean false Whether the combobox is disabled
filterOptions ComboboxFilterOptions {} Options for filtering the combobox items
isItemEqualToValue ComboboxItemEqualToValue<T> this._config.isItemEqualToValue A function to compare an item with the selected value.
itemToString ComboboxItemToString<T> | undefined this._config.itemToString A function to convert an item to a string for display.
filter ComboboxFilter<T> this._config.filter A custom filter function to use when searching.
value T[] | null null The selected values of the combobox.

Outputs

PropTypeDefaultDescription
valueChanged T[] | null null The selected values of the combobox.

BrnComboboxPopoverTrigger

Selector: [brnComboboxPopoverTrigger]

BrnComboboxSeparator

Selector: [brnComboboxSeparator]

Inputs

PropTypeDefaultDescription
orientation 'horizontal' | 'vertical' horizontal -

BrnComboboxTrigger

Selector: [brnComboboxTrigger]

BrnComboboxValue

Selector: [brnComboboxValue]

BrnComboboxValues

Selector: [brnComboboxValues]

BrnCombobox

Selector: [brnCombobox]

Inputs

PropTypeDefaultDescription
disabled boolean false Whether the combobox is disabled
filterOptions ComboboxFilterOptions {} Options for filtering the combobox items
isItemEqualToValue ComboboxItemEqualToValue<T> this._config.isItemEqualToValue A function to compare an item with the selected value.
itemToString ComboboxItemToString<T> | undefined this._config.itemToString A function to convert an item to a string for display.
filter ComboboxFilter<T> this._config.filter A custom filter function to use when searching.
value T | null null The selected value of the combobox.

Outputs

PropTypeDefaultDescription
valueChanged T | null null The selected value of the combobox.

Helm API

HlmComboboxChipInput

Selector: input[hlmComboboxChipInput]

HlmComboboxChipRemove

Selector: button[hlmComboboxChipRemove]

HlmComboboxChip

Selector: hlm-combobox-chip

Inputs

PropTypeDefaultDescription
showRemove boolean true -

HlmComboboxChips

Selector: [hlmComboboxChips],hlm-combobox-chips

HlmComboboxContent

Selector: [hlmComboboxContent]

HlmComboboxEmpty

Selector: [hlmComboboxEmpty],hlm-combobox-empty

HlmComboboxGroup

Selector: [hlmComboboxGroup]

HlmComboboxInput

Selector: hlm-combobox-input

Inputs

PropTypeDefaultDescription
placeholder string --
showTrigger boolean true -
showClear boolean false -
aria-invalid boolean false -

HlmComboboxItem

Selector: hlm-combobox-item

HlmComboboxLabel

Selector: [hlmComboboxLabel]

HlmComboboxList

Selector: [hlmComboboxList]

HlmComboboxMultiple

Selector: [hlmComboboxMultiple],hlm-combobox-multiple

HlmComboboxSeparator

Selector: [hlmComboboxSeparator]

HlmComboboxTrigger

Selector: hlm-combobox-trigger

Inputs

PropTypeDefaultDescription
class ClassValue --
variant ButtonVariants['variant'] outline -

HlmComboboxValue

Selector: [hlmComboboxValue]

HlmComboboxValues

Selector: [hlmComboboxValues]

HlmCombobox

Selector: [hlmCombobox],hlm-combobox

 Command Collapsible