The overlay component is used to display additional context information or to analyze charts, tags or tiles. The overlay's content should be reduced to a minimal amount of necessary components to display further information and actions.

You can also use them for analysing different chart types, infographics, tags or tiles (see overlays in use section).

<span
  [dtOverlay]="overlay"
  style="cursor: pointer"
  [dtOverlayConfig]="config"
  (pinnedChanged)="handle($event)"
>
  Hover me
</span>
<ng-template #overlay>
  <p>Overlay content</p>
</ng-template>

Imports

You have to import the DtOverlayModule when you want to use the DtOverlay service or the DtOverlayTriggerdirective. The DtOverlay service also requires Angular's BrowserAnimationsModule for animations. For more details on this see Step 2: Animations in the getting started guide.

@NgModule({
  imports: [DtOverlayModule],
})
class MyModule {}

Initialization

There are two ways to create overlays: using the DtOverlay service or the DtOverlayTrigger directive. The service can be used to apply overlays programatically or to pass components into the overlay. The directive can be used inside the template with a templateRef as the content of the overlay. The basic example above uses the DtOverlay service and passes an optional configuration (find details below) to the overlay.

DtOverlayTrigger directive

The DtOverlayTrigger directive can be applied to any element with the [dtOverlay]="overlay" attribute. The parameter overlay passed in this example is a reference to an ng-template that holds the content of the overlay. The configuration can be passed to the directive using the [dtOverlayConfig] input (see properties below).

The trigger has keyboard support: It opens the overlay on SPACE and ENTER when focused and closes the open overlay on ESCAPE.

When an overlay is active and the trigger gets destroyed, the overlay will be dismissed as well.

Inputs

Name Type Default Description
disabled boolean - When disabled is set to true the overlay does not open on hover.
tabIndex number 0 Sets the trigger's tabindex.
dtOverlay TemplateRef - Overlay pane containing the content.
dtOverlayConfig DtOverlayConfig - Overlay configuration; see properties below.

Outputs

Name Type Description
pinnedChanged EventEmitter<void> Will notify by firing every time the pinned state changes

Methods

Name Type Description
focus void Focuses the trigger.

DtOverlay service

You can get the DtOverlay service instance with dependency injection (DI) in any of your components.

...
constructor(private _dtOverlay: DtOverlay) {}
...

Methods

The DtOverlay service has the following two methods:

Method Parameters Return value Description
create() origin: DtOverlayOrigin
componentOrTemplateRef: ComponentType<T> | TemplateRef<T>
config?: DtOverlayConfig
DtOverlayRef (see details below) Creates a overlay connected to the origin and containing the given component or templateRef.
dismiss() - void Dismisses the currently open overlay. This method can be used if the overlay needs to be dismissed programatically.
<button dt-button (click)="createOverlay()">Create overlay</button>
<button dt-button (click)="dismiss()">Dismiss</button>
<p><span #origin>An overlay will be created here</span></p>

DtOverlayRef

The DtOverlay service create method returns an instance of DtOverlayRef. This reference can be used to perform updates on the position, pinning the overlay or dismissing it.

Methods

Method Parameters Return value Description
pin() value: boolean void Either pins or unpins the overlay.
dismiss() - void Dismisses the overlay.
updatePosition() offsetX: number
offsetY: number
void Sets an offset to the overlay's position. Can be used e.g. in a mousemove eventhandler to update the overlays position depending on the MouseEvent.
updateImplicitContext() data: any void Updates the implicit context on the template portal if one exists

DtOverlayConfig

This configuration is optional and can be passed to the service's create method or as an input to the trigger directive. The DtOverlayConfig class has the following properties:

Name Type Default Description
pinnable boolean - enables pinning of the overlay on click or by keyboard when the trigger is focused.
originY center | edge center The originY defines the vertical attachment point for the overlay. By default center is set. edge defines that the vertical attachment point is set to the bottom edge if the overlay fits below the origin element and the top edge otherwise.
movementConstraint xAxis | yAxis - The movementConstraint locks the movement of the overlay to a given axis. No constraint is set by default.
data any - The data passed to the overlay as the $implicit context object

Fullscreen support

The Overlay component uses Angular CDK's FullscreenOverlayContainer in order to supports correct displaying of overlays in DOM elements in fullscreen mode. Fullscreen API

<div #container class="dt-span-container">
  <span
    [dtOverlay]="overlay"
    style="cursor: pointer"
    [dtOverlayConfig]="config"
  >
    Hover me
  </span>
</div>
<button (click)="requestFullscreen()">Test Fullscreen</button>
<ng-template #overlay>
  <p>Overlay content</p>
</ng-template>

Overlays in use

Overlays appear on hover, focus, tap or click. They disappear on hover out, lost focus, tap, or click. As a general rule, only one overlay can be visible at a time. There may be exceptions for special use cases e.g. heat fields in charts.

To use the interactive elements it's necessary to pin overlays. This can be triggered either by click, focus, or tap. Pinning can be released by click, lost focus, or tap.

If an overlay contains interactive elements such as links or buttons, it should remain pinned to be able to use these elements. Normal overlays will always change to interactive overlays if used on touch. Interactive overlays always contain a nested close button.

Overlay content

The content in overlays can vary depending on the usage. Use our Angular components as content elements. As a general rule overlays should behave responsively. Overlays should always fit the available screensize and the content should reflow accordingly. When in doubt please contact an UX teammember.

<span [dtOverlay]="overlay" style="cursor: pointer" [dtOverlayConfig]="config">
  Hover me to show the overlay
</span>
<!-- prettier-ignore -->
<ng-template #overlay>
      <div class="dt-overlay-example-content-wrapper">
        <p>favicon_orange_plane.ico</p>
        <p>
          This resource was requested <strong>1.00 times per user action
          for a total of 117 calls.</strong> Detailed timings are available
          for <strong>100% of these calls</strong>.
        </p>
        <p>Overall</p>
        <dt-key-value-list>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Count</dt-key-value-list-key>
            <dt-key-value-list-value>117</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Cached</dt-key-value-list-key>
            <dt-key-value-list-value>no</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Load time</dt-key-value-list-key>
            <dt-key-value-list-value>28.1 ms</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Started at</dt-key-value-list-key>
            <dt-key-value-list-value>737 ms</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Completed at</dt-key-value-list-key>
            <dt-key-value-list-value>756 ms</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Resource type</dt-key-value-list-key>
            <dt-key-value-list-value>image</dt-key-value-list-value>
          </dt-key-value-list-item>
        </dt-key-value-list>
        <p>Sizes</p>
        <dt-key-value-list>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Transferred size</dt-key-value-list-key>
            <dt-key-value-list-value>106 kB</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Encoded size</dt-key-value-list-key>
            <dt-key-value-list-value>106 kB</dt-key-value-list-value>
          </dt-key-value-list-item>
          <dt-key-value-list-item>
            <dt-key-value-list-key>Compressed</dt-key-value-list-key>
            <dt-key-value-list-value>no</dt-key-value-list-value>
          </dt-key-value-list-item>
        </dt-key-value-list>
        <button dt-button>See response details</button>
      </div>
    </ng-template>

Table overlay

The information visible in the table overlay can also be found within an expanded table row. The information belonging to the hovered column will be highlighted within the overlay.

Table overlay

Tile overlay

<dt-tile color="main" [dtOverlay]="overlay">
  <dt-tile-icon><dt-icon name="loadaction"></dt-icon></dt-tile-icon>
  <dt-tile-title>Loading of page/special-offers.jsp</dt-tile-title>
  Hover me to see more details
</dt-tile>
<ng-template #overlay>
  <div class="dt-overlay-example-content-wrapper">
    <p>Loading of page/special-offers.jsp</p>
    <dt-key-value-list>
      <dt-key-value-list-item>
        <dt-key-value-list-key>User action duration</dt-key-value-list-key>
        <dt-key-value-list-value>4.9s</dt-key-value-list-value>
      </dt-key-value-list-item>
      <dt-key-value-list-item>
        <dt-key-value-list-key>User actions</dt-key-value-list-key>
        <dt-key-value-list-value>2.5/min</dt-key-value-list-value>
      </dt-key-value-list-item>
      <dt-key-value-list-item>
        <dt-key-value-list-key>Apdex rating</dt-key-value-list-key>
        <dt-key-value-list-value dtIndicator dtIndicatorColor="error">
          <dt-icon
            name="smiley-enraged-2"
            dtIndicator
            dtIndicatorColor="error"
          ></dt-icon>
          0.47
        </dt-key-value-list-value>
      </dt-key-value-list-item>
    </dt-key-value-list>
  </div>
</ng-template>

Tag overlay

Overlay example with tags

Do's and don'ts

Regular overlays should not

  • contain any interactive elements like links, buttons, drop-downs, scrollbars etc.
  • influence the mouse cursor (e.g. use "hand" cursor instead of normal pointer)

Interactive overlays should not

  • contain scrollbars, drop-downs, expandable sections, tabs etc.
  • be used together with components where clicking and tapping is already reserved for other interactions (e.g. click to pin hairline within a chart), because in this case it's not possible to pin the interactive overlay.