Angular CDK – Easy start with Overlay Module

Overlay is a very important module that is being widely used in Angular Applications. Very often you would need it to implement open floating panels on the screen. On top of this module were built such Angular Material components like Dialog Windows, Tooltips, Select, and so on. In this article, I will show you how you can easily start with this module and create your custom tooltip panel when the user focuses on some input.

I assume that you already have an Angular application but if you don’t then you have to install Angular CLI and create a new App. Then you need to install Angular CDK. Just run in your console:

ng add @angular/cdk

Then the first thing we have to do is to import the Overlay module in the module where you are going to use it, in my case it is app.module.ts:

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

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

Also, this module requires some CSS styles in order to work correctly. You can import these styles in your styles.scss|sass|css file:

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

Almost every component which uses Overlay Module has 2 basic elements:

• Connected Overlay – some template which should be shown (tooltip text or any another HTML)
• Overlay Origin – HTML element on a page Connected Overlay should be attached to. In our case it is going to be an input element because I want to should our tooltip next to the input

Now let’s create our Connected Overlay and Overlay Origin. I will go to app.component.html and the next HTML code there:

<input type="text" />

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

Looks quite good, we have an input element which should be the Overlay Origin and ng-template which is the content of the tooltip itself but how does Angular understand where is what? For this purpose we will use certain directives which provide Overlay Module – cdkOverlayOrigin and cdkConnectedOverlay and let’s attach them respectively:

<input type="text" cdkOverlayOrigin />

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

Ok, it looks already better but still… Just imagine that we have multiple origins (multiple inputs as an example), then Angular would be confused. So we need explicitly map them together. Let’s do it.

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

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

Now let me please quickly explain what we have done. We created a template variable #originOverlay and between quotes, we define explicitly that we want to read cdkOverlayOrigin instead of TemplateRef (Template Reference) which is by default. Then we provide our template variable to cdkConnectedOverlayOrigin input.

At this point, we are almost done. Now we just need to define when we want to show the tooltip. As I said before we are going to do it when we focus on the input. So let’s create a property isOpen in the typescript file (app.component.ts)

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

And now just set isOpen to true is we are focused on the input and to false if we are unfocused. Then we add this value to the cdkConnectedOverlayOpen property.

<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>

And that’s it! Now if you save your changes and go to the browser and focus on your input – you will see the tooltip next to it.

If you are looking for a more advanced use case for the Overlay Module – please check out my video.