Demo

Example application

Code playground

Run demo locally

Recommended versions to use

• Angular 8: ~2.0.4
• Angular 9+: @latest

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 or bind possible undefined property:

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

2. content prop :

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

3. passing string directly:

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

4. setContent()* method :

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

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

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

  constructor(private tippyService: NgxTippyService) {}

  ...

  ngAfterViewInit() {
    this.setContentForTooltip();
  }

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

*For this method tippyName should be defined

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

5. 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'
  }
}

6. template:

• Pass template 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

<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 | | setTriggerTarget() | name: string, triggerTarget: Element | Element[] | Set/update the trigger source | | 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'
  | 'setTriggerTarget'
  | '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">Singleton</button>

  <button ngxTippy="Tooltip content">Singleton</button>

  <button ngxTippy="Tooltip content">Singleton</button>

</ngx-tippy-singleton>

Use optional singletonProps for pass common props

Use optional singletonName for pass unique singleton name, need to control singletons 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"
  >
    Singleton
  </button>

  <button ngxTippy="Tooltip content">Singleton</button>

  <button
    ngxTippy="Tooltip content"
    data-tippy-arrow="false"
  >
    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">Singleton</button>

  <button ngxTippy="Tooltip content">Singleton</button>

  <button
    ngxTippy="Tooltip content"
    [tippyName]="'custom'"
  >
    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