Tableau UI for Angular

Dialogs

A dialog shows information or asks the user to decide, above the page.

Import

Inject DialogService from tableau-ui-angular/dialog: one for the app, so Escape closes the top dialog. On the server it shows nothing, and a confirmation resolves false at once.

Confirmation with a message

openConfirmationMessageDialog() resolves true when the user accepts. Its colour styles the accept button, and autofocus picks the button focus goes to as it opens, accept or cancel; without it, focus goes to cancel, the first.

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { DialogService } from 'tableau-ui-angular/dialog';
import { SnackService } from 'tableau-ui-angular/snack';

@Component({
  selector: 'app-dialog-confirm-example',
  imports: [TableauUiButtonModule],
  templateUrl: './dialog-confirm.example.html',
  styleUrl: './dialog-confirm.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class DialogConfirmExampleComponent {
  private readonly dialogs = inject(DialogService);
  private readonly snacks = inject(SnackService);

  // Resolves true when the user accepts, false when they cancel or close it
  protected async confirm(color: 'error' | 'primary' | 'secondary', autofocus?: 'accept' | 'cancel') {
    const accepted = await this.dialogs.openConfirmationMessageDialog(
      'Delete the item?',
      'Are you sure you want to delete this item? It goes for good, and this text runs to two lines to show how the dialog wraps.',
      color,
      undefined,
      undefined,
      autofocus,
    );
    this.snacks.openSnack(accepted ? 'Accepted' : 'Cancelled', 2000, 'info');
  }
}

Confirmation with a template

openConfirmationTemplateDialog() shows a template as the content, and takes the buttons' texts.

import type { TemplateRef } from '@angular/core';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiCheckboxModule } from 'tableau-ui-angular/checkbox';
import { DialogService } from 'tableau-ui-angular/dialog';
import { TableauUiIconModule } from 'tableau-ui-angular/icon';
import { SnackService } from 'tableau-ui-angular/snack';

@Component({
  selector: 'app-dialog-template-example',
  imports: [TableauUiButtonModule, TableauUiCheckboxModule, TableauUiIconModule],
  templateUrl: './dialog-template.example.html',
  styleUrl: './dialog-template.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class DialogTemplateExampleComponent {
  private readonly dialogs = inject(DialogService);
  private readonly snacks = inject(SnackService);

  // The template is the dialog's content, under its title and above its buttons, here with texts of their own
  protected async confirm(template: TemplateRef<unknown>, color: 'error' | 'primary' | 'secondary') {
    const accepted = await this.dialogs.openConfirmationTemplateDialog('Publish the workbook?', template, undefined, color, 'Custom Accept', 'Custom Cancel', 'accept', {
      width: '500px',
    });
    this.snacks.openSnack(accepted ? 'Accepted' : 'Cancelled', 2000, 'info');
  }
}

A component of its own

openModal() shows any component, with no buttons of its own. The component reads its data with injectDialogData() and closes with injectDialogRef(); closed$ gives the result. A modal without a header is named by label in its args, as the second dialog here is.

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { DialogService, injectDialogData, injectDialogRef } from 'tableau-ui-angular/dialog';
import { SnackService } from 'tableau-ui-angular/snack';

// The dialog's content: any component, which gets its data and its dialog through inject
@Component({
  selector: 'app-example-dialog',
  imports: [TableauUiButtonModule],
  template: `
    <h2>Example dialog</h2>
    <p>{{ message }}</p>
    <div class="buttons">
      <button (click)="openAnother()">Open another dialog</button>
      <button color="primary" (click)="close()">Close</button>
    </div>
  `,
  styles: `
    :host {
      display: block;
      padding: 1em 2em;
    }

    .buttons {
      display: flex;
      gap: 0.5rem;
    }
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ExampleDialogComponent {
  private readonly dialogs = inject(DialogService);
  private readonly dialogRef = injectDialogRef<string>();
  protected readonly message = injectDialogData<string>();

  protected close() {
    this.dialogRef.close('Closed with the Close button');
  }

  // A dialog can open another above it; Escape closes the top one. With no header, label names it for screen readers
  protected openAnother() {
    this.dialogs.openModal(ExampleDialogComponent, 'Another dialog', { height: 'auto', label: 'Another dialog' });
  }
}

@Component({
  selector: 'app-dialog-custom-example',
  imports: [TableauUiButtonModule],
  templateUrl: './dialog-custom.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class DialogCustomExampleComponent {
  private readonly dialogs = inject(DialogService);
  private readonly snacks = inject(SnackService);

  // No buttons of its own: the content closes the dialog, with a result, and the header's close button closes it without one
  protected open() {
    const dialogRef = this.dialogs.openModal<ExampleDialogComponent, string, string>(ExampleDialogComponent, 'This message is the dialog data', {
      width: 'calc(100vw - 100px)',
      maxWidth: '300px',
      height: 'fit-content',
      closeOnBackdropClick: true,
      header: {
        title: 'A custom dialog',
        allowClose: true,
      },
    });
    dialogRef.closed$.subscribe(result => {
      this.snacks.openSnack(result ?? 'Closed without a result', 2000, 'info');
    });
  }
}

Overlays in a modal

A modal sits in the browser's top layer, above every z-index of the page, and the page outside it is inert: an overlay outside the modal shows under it and takes no clicks or focus. So a tooltip, a snack, or a dialog the app opens with openDialog() or openTemplateDialog(), opened while a modal is open, goes into that modal: it sits above the modal's content and takes its clicks and focus. A select's list, an autocomplete's suggestions and a menu sit after their element, so in the modal already. A modal that closes first closes the dialogs in it, top first, and the snacks go back to the page. A modal opened from a modal, a confirmation included, goes to the body above it, so a modal can open the next one and close itself.

$overlayHost() is where an overlay opened now belongs: the topmost modal's overlay layer, div.dialog-overlay-layer at the end of its container, or null while no modal is open, for the body. The layer takes no space and sits above everything in the modal's content, a sticky toolbar or a map with a z-index of its own included. An app that appends an overlay of its own to the body appends it to $overlayHost() ?? document.body instead, position: fixed at the viewport coordinates getBoundingClientRect() gives: an absolute one is placed against the layer, which has no size, so page coordinates land low by the page's scroll and a percentage size is of nothing. When the modal closes, the service moves what the app put in the layer on to the next host, the topmost modal still open or the body; the app removes what should go with the modal. The overlays are position: fixed in the modal's container, so a transform, filter or contain on .dialog-container would move and clip them.

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { DialogService, GlobalStackOptions, injectDialogRef } from 'tableau-ui-angular/dialog';
import { SnackService } from 'tableau-ui-angular/snack';
import { TableauUiTooltipModule } from 'tableau-ui-angular/tooltip';

// A note the modal opens below its button with openDialog
@Component({
  selector: 'app-example-note',
  template: `<p>This dialog sits in the modal, and closes with it.</p>`,
  styles: `
    :host {
      display: block;
      padding: 0 1rem;
    }
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ExampleNoteComponent {}

// The modal's content: a tooltip, a snack and a dialog opened from here sit in the modal, above its content
@Component({
  selector: 'app-example-overlays-dialog',
  imports: [TableauUiButtonModule, TableauUiTooltipModule],
  template: `
    <p>Each overlay opened from this modal sits in it, above its content.</p>
    <div class="buttons">
      <button tooltip="A tooltip in the modal">Tooltip</button>
      <button (click)="snack()">Show a snack</button>
      <button (click)="note($event)">Open a dialog</button>
      <button color="primary" (click)="close()">Close</button>
    </div>
  `,
  styles: `
    :host {
      display: block;
      padding: 0 1.5rem 1rem;
    }

    .buttons {
      display: flex;
      flex-wrap: wrap;
      gap: 0.5rem;
    }
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ExampleOverlaysDialogComponent {
  private readonly dialogs = inject(DialogService);
  private readonly snacks = inject(SnackService);
  private readonly dialogRef = injectDialogRef();

  // It shows until the user closes it, and goes back to the page when the modal closes
  protected snack() {
    this.snacks.openSnack('This snack sits in the modal while it is open', 0, 'info');
  }

  // Placed below the button; a click outside it or Escape closes it, and so does the modal closing
  protected note(event: MouseEvent) {
    this.dialogs.openDialog(
      ExampleNoteComponent,
      undefined,
      {
        closeOnBackdropClick: true,
        closeOnEscape: true,
        containerCss: {
          backgroundColor: 'var(--twc-color-base)',
          border: '1px solid var(--twc-color-border-light)',
          boxShadow: 'var(--twc-dialog-box-shadow)',
        },
        top: (width, height, rect) => `${rect!.bottom + 4}px`,
        left: (width, height, rect) => `${rect!.left}px`,
      },
      new GlobalStackOptions(event.currentTarget as HTMLElement),
    );
  }

  protected close() {
    this.dialogRef.close();
  }
}

@Component({
  selector: 'app-dialog-overlays-example',
  imports: [TableauUiButtonModule],
  templateUrl: './dialog-overlays.example.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class DialogOverlaysExampleComponent {
  private readonly dialogs = inject(DialogService);

  protected open() {
    this.dialogs.openModal(ExampleOverlaysDialogComponent, undefined, {
      width: '28rem',
      header: { title: 'Overlays in a modal', allowClose: true },
    });
  }
}

Accessibility

A modal follows the WAI-ARIA dialog (modal) pattern: it is a <dialog> the service shows with showModal(), so the browser makes the rest of the page inert for the keyboard, the pointer and screen readers until it closes.

  • Screen readers hear a modal dialog named by its header's title. A modal without a header is named by label in its args; a dialog that isn't a modal, from openDialog() or openTemplateDialog(), ignores it. A confirmation is described by its message, which a screen reader reads with the button focus goes to.
  • As a modal opens, focus goes to the first of these: an element its content focused as it rendered, its content's first autofocus element, its first element in the Tab order, the header's close button, the modal itself. Content opened from a modal marks the element to focus autofocus rather than focusing it as it renders: until the new modal shows, it is outside the open one, inert, and takes no focus. A modal its content opens as it is made or renders, such as a confirmation from its ngOnInit, shows above it.
  • When it closes, focus goes back to the element focused before it opened, while that is still in the page. A modal that closes under one it opened, as a wizard's step does, leaves focus in the one still open, which gives it back there in its turn. A modal opened from a menu's item, as the menu closes, gives focus back to the menu's button; a menu opened with trapFocus false, or a button gone by the time the modal closes, leaves focus on the body.
  • A dialog that isn't a modal and keeps focus, such as a menu or one the app opens with trapFocus, keeps Tab in itself, and in the dialogs opened above it, such as one a menu item opens: Tab and Shift+Tab move as the browser moves them, a date input's own fields included, and wrap at either end. It gives focus back when it closes, and the page's own Tab order stays as it is.
  • Its backdrop is the <dialog>'s ::backdrop, in --twc-modal-color-backdrop; style it as dialog.dialog-container::backdrop.
Key or pressWhat it does
Escape Closes the top dialog in the modal, such as a select's list, then the modal, unless closeOnEscape is false. A showing tooltip takes it first. A handler of the app's, on an element in the modal or on the document, keeps the modal open with preventDefault(). Escape in a date or time input closes nothing, since it can come from closing the input's own picker
Tab, Shift+TabMove through the modal's elements; the page outside takes no focus
A press on the backdropCloses the modal, unless closeOnBackdropClick is false. The press starts and ends on the backdrop, so a text selection dragged out of the modal keeps it