Selection List
Table of Contents
Installation
Use the ng add command to quickly install all the needed dependencies:
ng add @terminus/ui-selection-listCSS 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
@Inputis namedreopenAfterSelection
<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;
| Function |
|---|
getSelectionListDebugElement |
getSelectionListInput |
getAllSelectionListDebugElements |
getAllSelectionListInstances |
getSelectionListInstance |
getSelectionListElement |
getSelectionListTriggerElement |
getAllOptionInstances |
getOptionInstance |
getOptionElement |
getAllOptgroups |
getOptgroup |
getOptgroupElement |