ngx-tooltip-directives

This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained ng2-tooltip-directive.

The latest library version is compatible with Angular 18.

Tooltips are informative pop-up tips that appear when you hover over or click on an item, providing helpful additional information or guidance.

Demo

https://mkeller1992.github.io/ngx-tooltip-directives/

Install

To install the library, enter the following command in your console:

npm i ngx-tooltip-directives

Setup

For apps based on Standalone Components

Import the directives for the respective tooltips directly in your component:

import { TooltipHtmlDirective, TooltipStrDirective, TooltipTemplateDirective } from '@ngx-tooltip-directives';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss'],
    standalone: true,
    imports: [TooltipStrDirective, TooltipHtmlDirective, TooltipTemplateDirective]
})

For apps based on ngModule

Make sure you import NgxTooltipDirectivesModule into your @NgModule:

import { NgxTooltipDirectivesModule } from 'ngx-tooltip-directives';
 
@NgModule({
    imports: [ NgxTooltipDirectivesModule ]
}) 

Usage

There are three ways of creating a tooltip:

Pass the tooltip text as a string via tooltipStr:

<div tooltipStr="Tooltip text">Show Tooltip</div>

Pass the tooltip content as SafeHtml via tooltipHtml:

<div [tooltipHtml]="safeTooltipHtml" placement="right">Show Html Tooltip</div>

import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
// Code skipped for brevity

export class AppComponent {
  rawHtml: string = '<div><p>This is a <strong>tooltip</strong> with HTML</p></div>';
  safeTooltipHtml: SafeHtml;

  constructor(private sanitizer: DomSanitizer){ 
    this.safeTooltipHtml = this.sanitizer.bypassSecurityTrustHtml(this.rawHtml);
  }
}

Pass the tooltip content as template via tooltipTemplate:

<ng-template #myTemplate>
  <div style="color: blue; font-weight: bold;">
    Tooltip Template
  </div>
</ng-template>

<div [tooltipTemplate]="myTemplate" placement="right">Show Tooltip Template</div>

Trigger tooltip programmatically

<div tooltip [tooltipStr]="'Tooltip text'" #myTooltip="tooltipStr"></div>

<button class="btn btn-small btn-outline btn-rounded" (click)="show()">show() via component.ts</button>
<button class="btn btn-small btn-outline btn-rounded" (click)="hide()">hide() via component.ts</button>

@ViewChild('myTooltip')
tooltip!: TooltipStrDirective;

show() {
  this.tooltip.show();
}

hide() {
  this.tooltip.hide();
}

3 ways of setting tooltip options

1 - Options can be set via html-attributes, so they have the highest priority:

<div tooltipStr="Tooltip on the right" textAlign="left" placement="right">Show Tooltip</div>

2 - Options can be passed to the tooltips as TooltipOptions object:

<div tooltipStr="Tooltip on the right" [options]="myOptions">Show Tooltip</div>

myOptions: TooltipOptions = {
    'placement': 'right',
    'showDelay': 500
}

3 - Options can be set globally when importing the module:

For apps based on Standalone Components:

import { NgxTooltipDirectivesModule, TooltipOptions } from 'ngx-tooltip-directives';

const myDefaultTooltipOptions: TooltipOptions = {
  'backgroundColor': 'yellow'
}

bootstrapApplication(AppComponent, {
  providers: [
    importProvidersFrom(
			NgxTooltipDirectivesModule.forRoot(myDefaultTooltipOptions)
		)
  ]
}).catch(err => console.error(err));

For apps based on ngModule's:

import { NgxTooltipDirectivesModule, TooltipOptions } from 'ngx-tooltip-directives';

const myDefaultTooltipOptions: TooltipOptions = {
  'backgroundColor': 'yellow'
}

@NgModule({
    imports: [ 
      NgxTooltipDirectivesModule.forRoot(myDefaultTooltipOptions)
    ]
})

Properties

Events

Events are called in accordance with the delays specified in the options within the directive. By default, there is a no delay before the tooltip hides.

Methods

If you have defined the directive options, these will be taken into consideration when calling the methods. This includes the delay before the tooltip appears and before it hides.

Testing with NgxTooltipDirectives

To simplify unit testing of components that use NgxTooltipDirectives, this library provides a set of mock directives as well as a mock module. You can use these mocks to bypass the actual directive behavior in your tests, focusing on the component logic instead.

Mocking when component under test is a standalone component

In the test initialization you might have to use .overrideComponent in order to override the actual directives with the mock-directives that are provided by my library.

import { TestBed } from "@angular/core/testing";
import { DomSanitizer } from "@angular/platform-browser";
import { MockTooltipHtmlDirective, MockTooltipStrDirective, MockTooltipTemplateDirective,
         TooltipHtmlDirective, TooltipStrDirective, TooltipTemplateDirective } from "@ngx-tooltip-directives";
import { AppComponent } from "./app.component";

describe("AppComponent", () => {
  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [ AppComponent ],
      providers: [
        { provide: DomSanitizer, useValue: { bypassSecurityTrustHtml: () => {} } },
      ]
    })
    .overrideComponent(AppComponent, {
      remove: {
        imports: [
          TooltipStrDirective,
          TooltipHtmlDirective,
          TooltipTemplateDirective
        ]
      },
      add: {
        imports: [
          MockTooltipStrDirective,
          MockTooltipHtmlDirective,
          MockTooltipTemplateDirective
        ]
      }
    })
    .compileComponents();
  });
  // Your tests here
});

Mocking when component under test is a NgModule-based component

Import MockNgxTooltipDirectivesModule in your test suite's TestBed configuration:

import { TestBed } from '@angular/core/testing';
import { AppComponent } from './app.component';
import { MockNgxTooltipDirectivesModule } from '@ngx-tooltip-directives';

describe('AppComponent', () => {
  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [AppComponent],
      imports: [MockNgxTooltipDirectivesModule]
    }).compileComponents();
  });

  // Your tests here
});