Tableau UI for Angular

Form Fields

A form field wraps an input with a label, hints, errors, a prefix and a suffix.

Import

Import TableauUiFormFieldModule from tableau-ui-angular/form-field. The typed forms, FB and their pipes, are in TableauUiFormModule from tableau-ui-angular/form, and suggestions in TableauUiAutoCompleteModule from tableau-ui-angular/autocomplete.

Value binding

Without a form, bind [value] and listen to (input) or (change); the field here shows a snack on each change. tab-hint sits under the input, on the left or with type="suffix" on the right.

Typed: nothing yet
Suffix
Hint on the left side
Hint on the right side
import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';
import { SnackService } from 'tableau-ui-angular/snack';

@Component({
  selector: 'app-form-field-value-example',
  imports: [TableauUiCommonModule, TableauUiFormFieldModule, TableauUiIconModule],
  templateUrl: './form-field-value.example.html',
  styleUrl: './form-field-value.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FormFieldValueExampleComponent {
  private readonly snacks = inject(SnackService);

  protected readonly $typed = signal('');

  // (input) fires on each key, (change) when the user leaves the field after changing it
  protected input(event: Event) {
    this.$typed.set((event.target as HTMLInputElement).value);
  }

  protected changed(event: Event) {
    this.snacks.openSnack(`Simple textbox set to: ${(event.target as HTMLInputElement).value || '<empty>'}`, 3000, 'info');
  }
}

Suggestions

[tabAutoComplete] opens a tab-autocomplete under the input, with its options, and a prefix and a suffix of its own. It shows while it has one of them: with none, as when the text matches no option and there is no prefix or suffix, it stays closed, and Escape goes to the page. This one searches as the user types.

import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { debounceTime, Subject } from 'rxjs';
import { TableauUiAutoCompleteModule } from 'tableau-ui-angular/autocomplete';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';

const NAMES = [
  'John Smith',
  'Jane Doe',
  'Michael Johnson',
  'Emily Davis',
  'William Brown',
  'Olivia Wilson',
  'James Taylor',
  'Sophia Martinez',
  'Benjamin Lee',
  'Isabella Anderson',
  'Henry Thomas',
  'Mia Jackson',
  'Daniel White',
  'Charlotte Harris',
  'Matthew Clark',
  'Amelia Lewis',
  'Andrew Walker',
  'Harper Young',
  'David Hall',
  'Evelyn Allen',
];

@Component({
  selector: 'app-form-field-autocomplete-example',
  imports: [TableauUiAutoCompleteModule, TableauUiCommonModule, TableauUiFormFieldModule, TableauUiIconModule],
  templateUrl: './form-field-autocomplete.example.html',
  styleUrl: './form-field-autocomplete.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FormFieldAutocompleteExampleComponent {
  protected readonly $search = signal('');
  protected readonly $searching = signal(false);
  protected readonly $results = signal(NAMES);
  protected readonly $count = computed(() => this.$results().length);

  private readonly typed = new Subject<string>();

  constructor() {
    // A search that takes a second, as a server's would, once the user stops typing
    this.typed.pipe(debounceTime(200), takeUntilDestroyed()).subscribe(search => {
      this.$searching.set(true);
      setTimeout(() => {
        const words = search.toLowerCase().split(' ');
        this.$results.set(NAMES.filter(name => words.every(word => name.toLowerCase().includes(word))));
        this.$searching.set(false);
      }, 1000);
    });
  }

  protected input(event: Event) {
    const { value } = event.target as HTMLInputElement;
    this.$search.set(value);
    this.typed.next(value);
  }
}

Reactive forms

Bind formControlName or [formControl]; a disabled control disables the field. These fields come from FB, whose controls give their value as value$.

Suffix
Hint on the left side
Hint on the right side
Suffix
Hint on the left side
Hint on the right side
Suffix
Hint on the left side
Hint on the right side
Set rows to make it taller from the start
Hint on the right side
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { debounceTime, skip } from 'rxjs';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import type { FC } from 'tableau-ui-angular/form';
import { FB, TableauUiFormModule } from 'tableau-ui-angular/form';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';
import { SnackService } from 'tableau-ui-angular/snack';

interface Fields {
  simple: string;
  placeholder: string;
  decorated: string;
  disabled: string;
  password: string;
  textarea: string;
}

@Component({
  selector: 'app-form-field-forms-example',
  imports: [TableauUiCommonModule, TableauUiFormModule, TableauUiFormFieldModule, TableauUiIconModule],
  templateUrl: './form-field-forms.example.html',
  styleUrl: './form-field-forms.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FormFieldFormsExampleComponent {
  private readonly fb = inject(FB);
  private readonly snacks = inject(SnackService);

  protected readonly form = this.fb.group<Fields>({
    simple: this.fb.control<string>(''),
    placeholder: this.fb.control<string>(''),
    decorated: this.fb.control<string>(''),
    // the fourth argument starts the control disabled
    disabled: this.fb.control<string>('', undefined, undefined, true),
    password: this.fb.control<string>(''),
    textarea: this.fb.control<string>(''),
  });

  constructor() {
    this.snackOnChange(this.form.controls.simple, 'Simple textbox');
    this.snackOnChange(this.form.controls.placeholder, 'Placeholder textbox');
    this.snackOnChange(this.form.controls.decorated, 'Decorated textbox');
    this.snackOnChange(this.form.controls.password, 'Password box');
    this.snackOnChange(this.form.controls.textarea, 'Text area');
  }

  // A snack once the user stops typing; value$ gives the current value first, which it skips
  private snackOnChange(control: FC<string>, name: string) {
    control.value$.pipe(skip(1), debounceTime(300), takeUntilDestroyed()).subscribe(value => {
      this.snacks.openSnack(`${name} set to: ${value || '<empty>'}`, 3000, 'info');
    });
  }
}

Validation

Show a tab-error when the control has an error: formMeta and formHasError read it, by name or any.

Suffix
Hint on the left side
Hint on the right side
Suffix
Enter -1 for two errors at once
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { Validators } from '@angular/forms';
import { debounceTime, skip } from 'rxjs';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import type { FC } from 'tableau-ui-angular/form';
import { FB, TableauUiFormModule } from 'tableau-ui-angular/form';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';
import { SnackService } from 'tableau-ui-angular/snack';

interface Fields {
  required: string;
  number: string;
}

@Component({
  selector: 'app-form-field-validation-example',
  imports: [TableauUiCommonModule, TableauUiFormModule, TableauUiFormFieldModule, TableauUiIconModule],
  templateUrl: './form-field-validation.example.html',
  styleUrl: './form-field-validation.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class FormFieldValidationExampleComponent {
  private readonly fb = inject(FB);
  private readonly snacks = inject(SnackService);

  protected readonly form = this.fb.group<Fields>({
    required: this.fb.control<string>('', Validators.required),
    number: this.fb.control<string>('', [Validators.required, Validators.min(0), Validators.pattern(/^\d+$/)]),
  });

  constructor() {
    this.snackOnChange(this.form.controls.required, 'Validated textbox');
    this.snackOnChange(this.form.controls.number, 'Number box');
  }

  // An error snack while the value is invalid; $meta() holds the control's validity
  private snackOnChange(control: FC<string>, name: string) {
    control.value$.pipe(skip(1), debounceTime(300), takeUntilDestroyed()).subscribe(value => {
      this.snacks.openSnack(`${name} set to: ${value || '<empty>'}`, 3000, control.$meta().validity === 'INVALID' ? 'error' : 'info');
    });
  }
}

Accessibility

The field names its control by the label and describes it by the hints and the errors; the app adds nothing.

The control getsHow
Its name The tab-label: its for names a native input, textarea or select, and aria-labelledby names the host of a select, a list or a radio group, or a chip control's search input
Its descriptionaria-describedby names the hints while they show, then the errors while they show
Its statearia-invalid="true" while an error shows
An announcementA hidden polite live region says an error that appears or changes while focus is in the field; one that appears while focus is elsewhere stays quiet

Ids the app puts in the control's own aria-describedby or aria-labelledby stay, with the field's after them.

On submit, move focus to the first invalid field. The fields say only the error of the field that has focus, so a submit that shows five errors stays quiet, and the user hears each error on reaching its field. Call markAllAsTouched() on the form, and once its errors show, focus the first element in it with aria-invalid="true". A radio group's host takes no focus: for a radio group, focus its checked radio, or else its first enabled one. The user then hears the field's name and its error once.