Skip to content

farengeyt451/ngx-tippy-wrapper

Repository files navigation

library logo

Angular wrapper for tippy.js

GitHub branch checks state Codecov branch GitHub

Demo

Example application

Code playground

Recommended versions to use

  • Angular 14, 15, 16: 6.x.x
  • Angular 13: 5.x.x
  • Angular 12: 4.x.x
  • Angular 9, 10, 11 3.x.x
  • Angular 8: 2.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 main or feature 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"
tippyContext NgxTippyContext [tippyContext]="{ aKey: 'something' }"

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

tippyContext - A way to bind any context you want to the template when using ng-template

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 be disabled on some conditions - you can explicitly pass null or undefined 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:

  1. data attribute:
<button
  ngxTippy
  data-tippy-content="Tooltip content"
>
  Element with tooltip
</button>
  1. content prop :
<button
  ngxTippy
  [tippyProps]="{
    allowHTML: true,
    content: '<p>Tooltip <strong>HTML</strong> content</p>'
  }"
>
  Element with tooltip
</button>
  1. 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

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

  1. 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'
  }
}
  1. ng-template:
<button
  [ngxTippy]="tooltipTemplate"
  [tippyContext]="{ item: { name: 'test' }}"
>
  Element with tooltip
</button>

<ng-template
  #tooltipTemplate
  let-name
  let-item="item"
>
  {{ name | json }}
  <h2>Content via ng-template, item's name = {{ item.name }}</h2>
</ng-template>

*You can get tippyName using outlet context

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

<template #template>
  <h2>HTML template</h2>
</template>
  1. component:
<button [ngxTippy]="component">Element with tooltip</button>

...
import { TippyTemplateComponent } from "...";
@Component({ ... })
export class DemoComponent implements OnInit {
  public component = TippyTemplateComponent;
}
  1. 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?: NgxTippyHideAllOptions 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

Documentation for v4.0.1