@terminus/ui-selection-list NPM

Installation

Use the ng add command to quickly install all the needed dependencies:

ng add @terminus/ui-selection-list

CSS imports

In your top-level stylesheet, add these imports:

@import '~@terminus/design-tokens/css/library-design-tokens.css';
@import '~@terminus/ui-styles/terminus-ui.css';

CSS resources

Load the needed font families by adding this link to the <head> of your application:

<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">

Usage

Pass a collection of ts-option components inside the selection-list:

<ts-selection-list [formControl]="myCtrl">
 <ts-option
    *ngFor="let state of states | async"
    [value]="state"
    [option]="state"
  >
    {{ state.name }}
  </ts-option>
</ts-selection-list>

Duplicate selections

By default, duplicate selections are ignored. They can be allowed via a flag:

<ts-selection-list
  [formControl]="myCtrl"
  [allowMultiple]="true"
  [allowDuplicateSelections]="true"
>
  ...
</ts-selection-list>

Keeping the panel open

By default, the panel will close after each selection. It can be forced to stay open via a flag.

NOTE: While the panel seems to stay open, it is actually closing and reopening immediately. That is why the @Input is named reopenAfterSelection

<ts-selection-list
  [formControl]="myCtrl"
  [allowMultiple]="true"
  [reopenAfterSelection]="true"
>
  ...
</ts-selection-list>

Debouncing queries

By default, the input query will be debounced 200ms. This time may be adjusted as needed:

<ts-selection-list
  [formControl]="myCtrl"
  [debounceDelay]="400"
>
  ...
</ts-selection-list>

Minimum characters

By default, at least two characters must be typed before the query is fired. This limit may be adjusted:

<ts-selection-list
  [formControl]="myCtrl"
  [minimumCharacters]="4"
>
  ...
</ts-selection-list>

Formatting

For complex object support, a formatter function may be passed in to define the view value:

<ts-selection-list
  [formControl]="myCtrl"
  [displayFormatter]="formatDisplay"
>
  ...
</ts-selection-list>

import { TsSelectionListFormatter } from '@terminus/ui-selection-list';

public formatDisplay: TsSelectionListFormatter = v => v.name;

Complex comparator

To compare custom objects, a compare function may be passed in:

<ts-selection-list
  [formControl]="myCtrl"
  [valueComparator]="myCompareFunction"
>
  ...
</ts-selection-list>

import { TsSelectionListComparator } from '@terminus/ui-selection-list';

public myCompareFunction: TsSelectionListComparator = (a, b) => a.id === b.id;

Standard dropdown mode (no typing)

If the component should act as a standard dropdown with no ability to type a query, set the flag allowUserInput to false. By default it is true.

<ts-selection-list
  [formControl]="myCtrl"
  [allowUserInput]="false"
>
  ...
</ts-selection-list>

Hint

A custom hint message can be displayed:

<ts-selection-list hint="Select at least one item"></ts-selection-list>

Error message

A custom error message can be displayed:

<ts-selection-list errorMessage="My error message!"></ts-selection-list>

noValidationOrHint

A flag to define whether this selectionlist field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.

<ts-selection-list
  [formControl]="myCtrl"
  [noValidationOrHint]="true"
></ts-selection-list>

Minimal

A minimal style is available:

<ts-selection-list [isMinimal]="true"></ts-selection-list>

Show progress

A progress indicator can be shown programmatically:

<ts-selection-list [showProgress]="true"></ts-selection-list>

Events

Event	Description	Payload
`backdropClicked`	Fired when the overlay backdrop is clicked	`void`
`closed`	Fired when the panel is closed	`void`
`duplicateSelection`	Fired when a duplicate selection is made	`TsSelectionListChange`
`opened`	Fired when the panel is opened	`void`
`optionSelected`	Fired when an option is selected	`TsSelectionListChange`
`optionDeselected`	Fired when an option is deselected	`TsSelectionListChange`
`queryChange`	Fired when the search query changes	`string`
`selectionChange`	Fired when the selected tab changes	`TsSelectionListChange`

<ts-selection-list (selectionChange)="whenSelectionChanges($event)">
  ...
</ts-selection-list>

The TsSelectionListChange structure:

class TsSelectionListChange<T = unknown> {
  constructor(
    // The associated selection list instance
    public source: TsSelectionListComponent,
    // The value
    public value: T,
  ) {}
}

Test Helpers

Some helpers are exposed to assist with testing. These are imported from @terminus/ui-selection-list/testing;

[source]

Function
`getSelectionListDebugElement`
`getSelectionListInput`
`getAllSelectionListDebugElements`
`getAllSelectionListInstances`
`getSelectionListInstance`
`getSelectionListElement`
`getSelectionListTriggerElement`
`getAllOptionInstances`
`getOptionInstance`
`getOptionElement`
`getAllOptgroups`
`getOptgroup`
`getOptgroupElement`