List
Import
Import TableauUiListModule from tableau-ui-angular/list for tab-list-single-select and tab-list-multi-select, and TableauUiCommonModule from tableau-ui-angular/common for tab-option. Each list is a listbox, for screen readers.
Options
A tab-option takes its text and hint as values or as templates, an icon with its [iconParams], and can be disabled. Without a form, bind [(value)].
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiListModule } from 'tableau-ui-angular/list';
@Component({
selector: 'app-list-options-example',
imports: [TableauUiCommonModule, TableauUiFormFieldModule, TableauUiListModule],
templateUrl: './list-options.example.html',
styleUrl: './list-options.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListOptionsExampleComponent {
protected readonly $value = signal<number | undefined>(undefined);
}Focus and display
A click picks an option. With the list focused, the up and down arrows move the highlight, and Enter or Space picks the highlighted option.
| Input | What it does |
|---|---|
focusMode | strong, the default, puts the list in the Tab order with a focus ring; silent with a faint one; none leaves it out of the Tab order |
selectedCheckIconLocation | Where a check marks the selected options: none, the default, left or right |
[selectedItemHighlight] | Highlights the selected options; true by default |
[itemTemplateContext] | Which of an option's icon, text and hint show |
[disabled] | Nothing can be picked, and the list is out of the Tab order |
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import type { IOptionGridContext } from 'tableau-ui-angular/common';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiListModule } from 'tableau-ui-angular/list';
interface Option {
value: number;
text: string;
icon?: string;
hint?: string;
disabled?: boolean;
}
@Component({
selector: 'app-list-display-example',
imports: [TableauUiCommonModule, TableauUiFormFieldModule, TableauUiListModule],
templateUrl: './list-display.example.html',
styleUrl: './list-display.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListDisplayExampleComponent {
protected readonly options: readonly Option[] = [
{ value: 1, text: 'Option 1', icon: 'home', hint: 'With an icon and a hint' },
{ value: 2, text: 'Option 2, disabled', hint: "It can't be picked", disabled: true },
{ value: 3, text: 'Option 3', icon: 'search', hint: 'With an icon and a hint' },
{ value: 4, text: 'Option 4', icon: 'home', hint: 'With an icon and a hint' },
];
// The lists share one value, so a pick in one shows in each
protected readonly $value = signal<number | undefined>(3);
protected readonly onlyText: IOptionGridContext = { renderIcon: false, renderText: true, renderHint: false };
}Height
A list is as tall as its options, unless its parent has a height: then the list fills it, and its options scroll inside it.
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiListModule } from 'tableau-ui-angular/list';
@Component({
selector: 'app-list-height-example',
imports: [TableauUiCommonModule, TableauUiFormFieldModule, TableauUiListModule],
templateUrl: './list-height.example.html',
styleUrl: './list-height.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListHeightExampleComponent {
protected readonly options = Array.from({ length: 8 }, (_, index) => ({ value: index + 1, text: `Option ${index + 1}` }));
protected readonly $value = signal<number | undefined>(undefined);
}Reactive forms
Bind [formControl] or formControlName. The control is touched when focus leaves the list, and a disabled control disables it. A tab-list-multi-select's value is an array: a click adds an option to it, or takes it out.
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { Validators } from '@angular/forms';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { FB, TableauUiFormModule } from 'tableau-ui-angular/form';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';
import { TableauUiListModule } from 'tableau-ui-angular/list';
interface Option {
value: number;
text: string;
icon?: string;
hint?: string;
disabled?: boolean;
}
@Component({
selector: 'app-list-forms-example',
imports: [TableauUiCommonModule, TableauUiFormModule, TableauUiFormFieldModule, TableauUiIconModule, TableauUiListModule],
templateUrl: './list-forms.example.html',
styleUrl: './list-forms.example.scss',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ListFormsExampleComponent {
private readonly fb = inject(FB);
protected readonly options: readonly Option[] = [
{ value: 1, text: 'Option 1', icon: 'home', hint: 'With an icon and a hint' },
{ value: 2, text: 'Option 2, disabled', hint: "It can't be picked", disabled: true },
{ value: 3, text: 'Option 3', icon: 'search', hint: 'With an icon and a hint' },
{ value: 4, text: 'Option 4, above the maximum', icon: 'home', hint: 'The validators allow 1 to 3' },
];
// Each starts at 4, above Validators.max(3): its error shows once the user leaves the list, as formHasError waits for
// the control to be touched
private readonly validators = [Validators.required, Validators.min(1), Validators.max(3)];
protected readonly single = this.fb.control<number | null>(4, this.validators);
protected readonly prefixed = this.fb.control<number | null>(4, this.validators);
// the fourth argument starts the control disabled
protected readonly disabled = this.fb.control<number | null>(2, undefined, undefined, true);
// A multi-select list's value is an array; a click adds an option, or takes it out
protected readonly multi = this.fb.control<number[] | null>([1, 3], [Validators.required]);
protected readonly $multiValue = computed(() => {
const values = this.multi.$value() ?? [];
return values.length > 0 ? values.join(', ') : 'none';
});
}