Angular CDK – Easy start with Overlay Module

Getting Started with the Angular CDK Overlay Module

The Overlay module is a cornerstone of many Angular applications. It powers the creation of floating panels, and it underpins several Angular Material components, including dialogs, tooltips, and selects. This guide demonstrates how to build a custom tooltip that appears when an input field receives focus using the CDK Overlay.

Before proceeding, ensure you have an existing Angular project. If not, you can install Angular CLI and scaffold a new one. Next, install Angular CDK by running the following command in your terminal:

ng add @angular/cdk

The initial setup step involves importing OverlayModule into the module where it will be used. In this example, that is app.module.ts:

// app.module.ts
// ... other imports
import { OverlayModule } from '@angular/cdk/overlay';

@NgModule({
  imports: [
     // ... other imports
     OverlayModule // <-- Import the module
  ],
})

The module also depends on some global CSS. These styles must be included in your global stylesheet (styles.scss, styles.sass, or styles.css):

@import '~@angular/cdk/overlay-prebuilt.css';

Most implementations using the Overlay Module revolve around two key entities:

• Connected Overlay – the template that gets displayed, such as tooltip content or any other HTML.
• Overlay Origin – the page element to which the Connected Overlay is anchored. Here, we use an input element as the origin since our goal is to display a tooltip beside it.

Let's define both entities in app.component.html:

<input type="text" />

<ng-template>
  <div>This is my tooltip</div>
</ng-template>

We now have an input as the Overlay Origin and an ng-template holding the tooltip content. To link them and clarify their roles for Angular, we apply the cdkOverlayOrigin and cdkConnectedOverlay directives provided by the Overlay Module:

<input type="text" cdkOverlayOrigin />

<ng-template cdkConnectedOverlay>
  <div>This is my tooltip</div>
</ng-template>

This setup is functional, but it becomes ambiguous when multiple origins exist, like several inputs. Angular needs explicit mapping between each origin and its overlay. Here is how to achieve that:

<input type="text" cdkOverlayOrigin #originOverlay="cdkOverlayOrigin" />

<ng-template cdkConnectedOverlay [cdkConnectedOverlayOrigin]="originOverlay">
  <div>This is my tooltip</div>
</ng-template>

Let's break down the code above. We introduced a template variable #originOverlay that explicitly reads the cdkOverlayOrigin directive rather than the default TemplateRef. This reference is then passed to the cdkConnectedOverlayOrigin input on the connected overlay.

With the connections in place, the next step is to control the tooltip's visibility. Our trigger is focusing the input. First, add an isOpen property in app.component.ts:

@Component({
  // your component
})
export class AppComponent {
  isOpen = false;
}

Now, update isOpen to true during input focus and false when focus is lost. Bind this value to the cdkConnectedOverlayOpen property on the overlay:

<input type="text"
       cdkOverlayOrigin
       #originOverlay="cdkOverlayOrigin"
       (focus)="isOpen = true"
       (blur)="isOpen = false"
/>

<ng-template cdkConnectedOverlay
             [cdkConnectedOverlayOrigin]="originOverlay"
             [cdkConnectedOverlayOpen]="isOpen"
>
  <div>This is my tooltip</div>
</ng-template>

That completes the implementation. Once you save and run the application, focusing the input will display the tooltip right next to it.

For deeper exploration of the Overlay Module's advanced features, check out the video linked below.