Tableau UI for Angular

List

A list shows its options in place, and the user picks one value from it, or several.

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)].

This is a looooooooooooooooong option, given as values
There are 2 ways to create tab-options: by values and by templates
Disabled value
with a hint
This option is given as a template
There are 2 ways to create tab-options: by values and by templates
This option is given as a combination of a template and values
with a hint
Value: none
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.

InputWhat it does
focusModestrong, 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
selectedCheckIconLocationWhere 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
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4
With an icon and a hint
Tab focuses it, with a strong focus ring
Option 1
Option 2, disabled
Option 3
Option 4
Tab passes it by
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4
With an icon and a hint
Tab focuses it, with a faint focus ring
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4
With an icon and a hint
Nothing can be picked, and Tab passes it by
Value: 3
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.

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
The options scroll inside the list
Option 1
Option 2
Option 3
Option 4
Option 5
Option 6
Option 7
Option 8
The list is taller than its options
Value: none
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.

Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4, above the maximum
The validators allow 1 to 3
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4, above the maximum
The validators allow 1 to 3
A disabled control disables the list
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4, above the maximum
The validators allow 1 to 3
A suffix
Option 1
With an icon and a hint
Option 2, disabled
It can't be picked
Option 3
With an icon and a hint
Option 4, above the maximum
The validators allow 1 to 3
Value: 1, 3
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';
  });
}