Angular wrapper for Tippy.js

Demo

Recommended versions to use

Angular 8: 2.x.x
Angular 9, 10, 11 3.x.x
Angular 12: 4.x.x

Installation

Install from npm:

npm i ngx-tippy-wrapper --save

Before upgrade

Migration guide

Importing

Import NgxTippyModule:

import { NgxTippyModule } from 'ngx-tippy-wrapper';

Then in your base module:

@NgModule({
    imports: [
        ...,
        NgxTippyModule
    ],
    ...
})

Import tippy.css style file to your main style file:

@import 'tippy.js/dist/tippy.css';

or angular.json:

"architect": {
"build": {
  ...,
  "options": {
    ...,
    "styles": [..., "./node_modules/tippy.js/dist/tippy.css"]
  }

Usage

Basic usage

Apply ngxTippy directive for element and pass content through data-tippy-content attribute:

<button ngxTippy data-tippy-content="Tooltip content">Element with tooltip</button>

Applying props

You can apply props with tippyProps binding

In template:

<button
  ngxTippy
  data-tippy-content="Tooltip content"
  [tippyProps]="{
    arrow: false,
    placement: 'bottom'
  }"
>
  Element with tooltip
</button>

Or pass props from component:

<span ngxTippy data-tippy-content="Tooltip content" [tippyProps]="tippyProps"> Element with tooltip </span>

...
import { NgxTippyProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {
  tippyProps: NgxTippyProps = {
    trigger: 'click',
    allowHTML: true,
  };
  ...
}

Implemented props

Prop name	Type	Example
`tippyProps`	NgxTippyProps	[tippyProps]="{ arrow: false, placement: 'bottom' }"
`tippyName`	string	tippyName="awesomeName"
`tippyClassName`	string	tippyClassName="new-class" or tippyClassName="new-class another-class"

tippyProps - list of all props

tippyName - name for tippy instance, required for accessing and control specific instance

tippyClassName - add custom class to the tippy-box element, support multiple classes passed as words separated by space

Initializing on condition

In some cases tooltip should be initialized conditionally. For example in case optional @Input property passed or not. So, if tooltip should not initialize - you can explicitly pass null through ngxTippy directive.

...
import { NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit, AfterViewInit {
  @Input() inputContent?: string;
}

<button class="t-demo__btn" [ngxTippy]="someCondition ? 'Content' : null">Element with tooltip</button>

or

<button class="t-demo__btn" [ngxTippy]="inputContent">Element with tooltip</button>

Applying content

You can pass tooltip content through:

data attribute:

<button ngxTippy data-tippy-content="Tooltip content">Element with tooltip</button>

content prop :

<button
  ngxTippy
  [tippyProps]="{
    allowHTML: true,
    content: '<p>Tooltip <strong>HTML</strong> content</p>'
  }"
>
  Element with tooltip
</button>

passing content directly:

<button ngxTippy="'Directly passed content'">Element with tooltip</button>

3.1 passing some variable directly*:

<button ngxTippy="content">Element with tooltip</button>

...
import { NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit, AfterViewInit {
  content: string = 'Tooltip content';

  setNewContentForTooltip() {
    this.content = 'Tooltip content'
  }
}

*Tooltip content updates automatically

setContent()* method :

<button ngxTippy tippyName="content">Element with tooltip</button>

...
import { NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit, AfterViewInit {
  boundContent: string = 'Bound tooltip content';

  constructor(private tippyService: NgxTippyService) {}

  ...

  ngAfterViewInit() {
    this.setContentForTooltip();
  }

  setContentForTooltip() {
    this.tippyService.setContent('content', this.boundContent);
  }
}

*For this method tippyName should be defined

*This method can be used for dynamic applying content at any time, not only in lifecycle hooks

tippyProps:

<button ngxTippy [tippyProps]="tippyProps">Element with tooltip</button>

...
@Component({ ... })
export class DemoComponent implements OnInit {
  tippyProps: NgxTippyProps = { ... }

  ...

  ngOnInit() {
    this.setContentForTooltip();
  }

  setContentForTooltip() {
    this.tippyProps.content = 'Initial tooltip content'
  }
}

ng-template:

<button [ngxTippy]="tooltipTemplate">Element with tooltip</button>

<ng-template #tooltipTemplate let-name>
  {{ name | json }}
  <h2>Content via ng-template</h2>
</ng-template>

*You can get tippyName using outlet context

HTML template

<button [ngxTippy]="template">Element with tooltip</button>

<template #template>
  <h2>HTML template</h2>
</template>

component:

<button [ngxTippy]="component">Element with tooltip</button>

...
import { TippyTemplateComponent } from "...";
@Component({ ... })
export class DemoComponent implements OnInit {
  public component = TippyTemplateComponent;
}

element reference:

Pass element reference directly

<button
  [ngxTippy]="tippyTemplate"
  tippyName="content"
  [tippyProps]="tippyContent"
>
  Element with tooltip
</button>

<div #tippyTemplate>
  <h4>Caption</h4>
  <p>Some content</p>
  <button (click)="...">Action</button>
  ...
</div>

Pass element, element.innerHTML using service

<div>
  <button
    ngxTippy
    tippyName="content"
    [tippyProps]="tippyProps"
  >
    Element with tooltip
  </button>

  <!-- If passing element itself -->
  <div #tippyTemplate>
    <h4>Caption</h4>
    <p>Some content</p>
    <button (click)="...">Action</button>
    ...
  </div>

  <!-- If passing element `innerHTML` -->
  <div #tippyTemplate style="display: none;">
    <h4>Caption</h4>
    <p>Some content</p>
    ...
  </div>
</div>

...
import { NgxTippyProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements AfterViewInit {
  @ViewChild('tippyTemplate', { read: ElementRef, static: true }) tippyTemplate: ElementRef;
  tippyContent: NgxTippyProps = { ... };

  constructor(private ngxTippyService: NgxTippyService) {}

  ngAfterViewInit() {
    this.setContentForTooltip();
  }

  setContentForTooltip() {
    const template = this.tippyTemplate.nativeElement;

    // Pass element itself
    this.ngxTippyService.setContent('content', template);

    // or

    // Pass element `innerHTML`
    this.ngxTippyService.setContent('content', template.innerHTML);
  }
  ...
}

Methods

Import and provide NgxTippyService:

...
import { NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {
  constructor(private tippyService: NgxTippyService) {}
  ...
}

For accessing and control specific tippy instance tippyName should be defined

Through service you can use all methods described here and some additional

Implemented methods

Get instance(s)

Method name	Method parameter/parameters	Method short description
getInstance()	`name`: string	Get specific instance
getInstances()	-	Get all tippy instances

Instance methods

Method name	Method parameter/parameters	Method short description
show()	`name`: string	Programmatically show the tippy
hide()	`name`: string	Programmatically hide the tippy
hideWithInteractivity()	`name`: string, `mouseEvent`: MouseEvent	Will hide the tippy only if the cursor is outside of the tippy's interactive region
disable()	`name`: string	Temporarily prevent a tippy from showing or hiding
enable()	`name`: string	Re-enable a tippy
setProps()	`name`: string, `tippyProps`: NgxTippyProps	Set/update any tippy props
setContent()	`name`: string, `tippyContent`: NgxTippyContent	Set/update the content
unmount()	`name`: string	Unmount the tippy from the DOM
clearDelayTimeouts()	`name`: string	Clears the instances delay timeouts
destroy()	`name`: string	Permanently destroy and clean up the tippy instance

Static methods

Method name	Method parameter/parameters	Method short description
setDefaultProps()	`tippyProps`: NgxTippyProps	Set the default props for each new tippy instance
showAll()	-	Show all tippies
hideAll()	`options?`: NgxHideAllOptions	Hide all tippies or hide all except a particular one, additional hide them with duration

Subscription for tippy instances change

...
import { Subscription } from 'rxjs';
import { NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit, OnDestroy {
  private instancesChanges$: Subscription;

  constructor(private tippyService: NgxTippyService) {}

  ngOnInit() {
    this.subToInstancesChanges();
  }

  ngOnDestroy() {
    this.instancesChanges$ && this.instancesChanges$.unsubscribe();
  }

  subToInstancesChanges() {
    this.instancesChanges$ =
      this.ngxTippyService.instancesChanges.subscribe((changes: InstancesChanges) => { ... });
  }

  ...
}

It provides information in format:

{
  name: string;
  reason: InstanceChangeReason;
  instance: NgxTippyInstance;
}

type InstanceChangeReason =
  | 'setInstance'
  | 'show'
  | 'hide'
  | 'hideWithInteractivity'
  | 'disable'
  | 'enable'
  | 'setProps'
  | 'setContent'
  | 'unmount'
  | 'clearDelayTimeouts'
  | 'destroy';

Grouped tooltips

If you want to give different tooltip content to many different elements, while only needing to initialize once with shared props - use ngx-tippy-group component:

<ngx-tippy-group [groupedProps]="groupedProps">

  <button data-tippy-grouped data-tippy-content="Tooltip content">Element with tooltip</button>

  <button data-tippy-grouped data-tippy-content="Tooltip content">Element with tooltip</button>

</ngx-tippy-group>

For each tooltip within component you should pass data-tippy-grouped attribute

Also you can pass new content and props through attribute for every tooltip element, see customization:

<ngx-tippy-group [groupedProps]="groupedProps">
  <button
    data-tippy-grouped
    data-tippy-content="Tooltip content"
  >
    Grouped
  </button>

  <button
    data-tippy-grouped
    data-tippy-arrow="false"
    data-tippy-content="Tooltip content"
  >
    Grouped
  </button>

  <button
    data-tippy-grouped
    data-tippy-delay="[1000, 200]"
    data-tippy-content="Tooltip content"
  >
    Grouped
  </button>
</ngx-tippy-group>

...
import { NgxTippyProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {
  groupedProps: NgxTippyProps = { ... };
  ...
}

Multiple tooltips on a single element

For multiple tooltips on a single element - use nest elements with applied ngxTippy directive:

<div
  ngxTippy
  data-tippy-content="First tooltip content"
  [tippyProps]="{ ... }"
>
  <div
    ngxTippy
    data-tippy-content="Second tooltip content"
    [tippyProps]="{ ... }"
  >
    <button
      ngxTippy
      data-tippy-content="Third tooltip content"
      [tippyProps]="{ ... }"
    >
      Element with tooltips
    </button>
  </div>
</div>

Singleton

For singleton - provide tooltip elements within ngx-tippy-singleton component:

<ngx-tippy-singleton
  [singletonProps]="singletonProps"
  singletonName="main-page"
>

  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

</ngx-tippy-singleton>

For each tooltip within component you should pass data-tippy-singleton attribute

Use optional singletonProps for pass common props

Use optional singletonName for pass unique singleton name, need to manual control specific singleton instance

programmatically

Overrides props

To overrides common singletonProps by the individual tippy props:

<ngx-tippy-singleton [singletonProps]="singletonProps">
  <button
    ngxTippy="Tooltip content"
    data-tippy-placement="bottom"
    data-tippy-singleton
  >
    Singleton
  </button>

  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

  <button
    ngxTippy="Tooltip content"
    data-tippy-arrow="false"
    data-tippy-singleton
  >
    Singleton
  </button>
</ngx-tippy-singleton>

...
import { NgxSingletonProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {

  singletonProps: NgxSingletonProps = {
    ...,
    overrides: ['arrow', 'placement'],
  };
  ...
}

Smooth transitions

Use the moveTransition prop, which is the transition between moves:

...
import { NgxSingletonProps } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {

  singletonProps: NgxSingletonProps = {
    ...,
    moveTransition: 'transform 0.4s linear',
  };
  ...
}

Programmatically control singleton instance

Get singleton instance(s)

Method name	Method parameter/parameters	Method short description
getSingletonInstance()	`name`: string	Get specific singleton instance
getSingletonInstances()	-	Get all tippy singleton instances

You can use all methods described here

In addition for show() method is possible to pass child [tippyName] prop

<ngx-tippy-singleton
  [singletonProps]="..."
  singletonName="main-page"
>
  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

  <button ngxTippy="Tooltip content" data-tippy-singleton>Singleton</button>

  <button
    ngxTippy="Tooltip content"
    [tippyName]="'custom'"
    data-tippy-singleton
  >
    Singleton
  </button>
</ngx-tippy-singleton>

...
import { NgxSingletonProps, NgxTippyService } from 'ngx-tippy-wrapper';

@Component({ ... })
export class DemoComponent implements OnInit {

  constructor(private tippyService: NgxTippyService) {}

  tippyProps: NgxSingletonProps = { ... };

  ngAfterViewInit() {

    // Get singleton instance by name
    const mainPageSingleton = this.tippyService.getSingletonInstance('main-page');

    // Programmatically manipulate tooltips

    // Show first child in singleton
    mainPageSingleton.show();

    // Show child instance at given index
    mainPageSingleton.show(1);

    // Show child `[tippyName]`
    mainPageSingleton.show('custom');

    ...
  }
}

Documentation for v1.0.1

Documentation for v2.1.0

Documentation for v3.0.1

moJiXiang / ngx-tippy-wrapper