NgxTooltip

Built on top of Tippy.js

Install

npm i @teamhive/ngx-tooltip

Getting Started

example.module.ts

⋮
import { NgModule } from '@angular/core';
import { TooltipModule, TooltipOptions } from '@teamhive/ngx-tooltip';

@NgModule({
    ⋮
    imports: [
        TooltipModule.forRoot({
            // custom defaults go here e.g.
            placement: 'top',
            arrow: 'true',
            arrowType: 'sharp',
            allowHTML: true,
            maxWidth: 200
        } as TooltipOptions)
    ]
    ⋮
})
export class ExampleModule { }

Usage

Basic

example.component.html

<div ngxTooltip tooltipContent="Lorem ipsum dolor…"> … </div>

HTML Content

⚠️   you should almost certainly santitize any html you didn't make yourself!

example.component.ts

import { TooltipContent } from '@teamhive/ngx-tooltip';
⋮
tooltipElement: TooltipContent;
⋮
ngOnInit() {
    this.tooltipElement = document.getElementById('tooltip-template');
    ⋮
}
⋮

example.component.html

<div ngxTooltip [tooltipAllowHtml]="true" tooltipContent="<span> … </span>"> … </div>

<!-- or -->

<span id="tooltip-template"> … </span>
<div ngxTooltip [tooltipAllowHtml]="true" [tooltipContent]="templateElement"> … </div>

<!-- or, best yet (Yay for template reference variables!!!!) -->

<span #tooltipTemplate> … </span>
<div ngxTooltip [tooltipAllowHtml]="true" [tooltipContent]="tooltipTemplate"> … </div>

Specify Options

example.component.ts

import { TooltipOptions } from '@teamhive/ngx-tooltip';
⋮
tooltipOptions: TooltipOptions = {
    placement: 'top',
    arrow: 'true',
    arrowType: 'sharp',
    allowHTML: true,
    content: '<span …> … </span>'
};
⋮

example.component.html

<div [ngxTooltip]="{content: 'Lorem ipsum dolor…', maxWidth: 200 …}"> … </div>

<!-- or -->

<div [ngxTooltip]="tooltipOptions"> … </div>

TooltipService

example.component.ts

import { TooltipService } from '@teamhive/ngx-tooltip';
⋮
constructor(tooltipService: TooltipService) {}
⋮
forceCloseAll() {
    tooltipService.hideAll();
}
⋮

| method | description | return type | |---|---|---| | hideAll() | Hides each TooltipInstance | void | | showAll() | Shows each TooltipInstance | void | | enableAll() | Enables each TooltipInstance except those without content to prevent empty tooltips from being displayed. | void | | disableAll() | Disables each TooltipInstance | void | | destroyAll() | Destroys each TooltipInstance | void | | getGroup() | Returns group TooltipInstance collection | Map<string | number, TooltipInstance> |

Properties

Some commonly used options are made available through element properties. see full list of options.

| property | description | type | |---|---|---| |ngxTooltip| all options can be passed via the directive itself | TooltipOptions | |tooltipGroup| specifies a group collection the tooltip should belong to. Actions can be applied to an entire group via the TooltipService. This property is custom to NgxTooltip and does not have a tippy.js equivalent. | string | number | |tooltipContent| The content of the tooltip. Along with a string or element, you can use a function that takes the reference element as an argument and returns content. | TooltipContent string | Element | ((ref: Element) => Element | string) | |tooltipPlacement| Positions the tippy relative to its reference element. Use the suffix '-start' or '-end' to shift the tippy to the start or end of the reference element, instead of centering it. For example, top-start or left-end. | TooltipPlacement 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' | |tooltipAnimation| The type of transition animation. | TooltipAnimation'shift-away' | 'shift-toward' | 'fade' | 'scale' | 'perspective' | |tooltipTrigger| The events (each separated by a space) which cause a tippy to show. Possible values: "mouseenter", "focus", "click", "manual". Use "manual" to only trigger the tippy programmatically. | string | | tooltipTouch | Determines if tooltip works on touch devices | boolean | | tooltipTouchHold | Determines trigger behavior on touch devices. Instead of a tap on the reference to show and a tap elsewhere to hide the tippy, the reference must be pressed and held for the tippy to show. Letting go from the screen will hide it. | boolean | |tooltipArrowType| Determines the arrow type. Using this property automatically enables the arrow option | TooltipArrowType'sharp' | 'round' | |tooltipMaxWidth| Determines the maximum width of the tippy - use a number for pixels, or a string to add units such as rem. In CSS, it's defined as 350px by default. This option applies the width to the style attribute of the tippy element. | number | string |tooltipTheme| Themes added as classes (each separated by a space) to the ngx-tooltip element's. | string |tooltipAllowHtml | Determines if the tooltip can have HTML content rendered inside of it. | boolean |

Additional properties

cannot be set via Element properties

| property | description | type | |---|---|---| | id | tooltip instance unique numeric id. | number | | state | object defining the sate of tooltip instance | TooltipState | | group | optional tooltip instance group id | string | number |

Methods

Some commonly used options are made available through element properties.

| method | description | return type | |---|---|---| | hide() | Force hides tooltip. | void | | show() | Force shows tooltip even if disabled. | void | | enable() | Force enables tooltip, unless it is without content, to prevent empty tooltips from being displayed. | void | | disable() | Force disables tooltip. | void | | destroy() | Force destroys tooltip. | void |

Theming

@teamhive/ngx-tooltip makes use of css variables for theming.

When you pass a theme name via TooltipModule.forRoot{}, ngxTooltip, or tooltipTheme - a css class is attached to the tooltip elements so they can be targeted for styling.

CSS Variables

| Variable | Description | |---|---| | --tooltip-color | Full CSS color property. | | --tooltip-arrow-color | Color of arrow. Used for various properties necessary to properly & uniformly color arrow. It is highly recommended to keep same as background color. | | --tooltip-background-color | Full CSS background-color property. | | --tooltip-font-size | Full CSS font-size property. | | --tooltip-font-weight | Full CSS font-weight property. | | --tooltip-font-style | Fulll CSS font-style property. | | --tooltip-font-family | Full CSS font-famliy property. | | --tooltip-box-shadow | Full CSS box-shadow property. | | --tooltip-border-radius | Full CSS border-radius property. | | --tooltip-text-align | Full CSS text-align property. | | --tooltip-padding | Full CSS padding property. |

example.scss

// the package styles.css file must be imported to use css variables
@import "@teamhive/ngx-tooltip/assets/styles/styles.css";

// custom styling should be placed in class selector of `${customThemeName}-theme`
.currant-theme {
    --tooltip-color: #9df2a4;               // seafoam
    --tooltip-arrow-color: #463E53;         // blackcurrant
    --tooltip-background-color: #463E53;    // blackcurrant
    --tooltip-font-size: 16px;
    --tooltip-font-weight: 500;
    --tooltip-font-style: normal;
    --tooltip-font-family: "Helvetica Neue", Helvetica, sans-serif;
    --tooltip-box-shadow: 2px 2px 5px grey;
    --tooltip-border-radius: 5px;
    --tooltip-text-align: center;
    --tooltip-padding: 5px;
}

example.component.html

<div ngxTooltip tooltipTheme="currant" tooltipContent="blackcurrant & seafoam"…>
    custom theme
</div>

for advanced theming, see the Tippy.js theming docs.

All Options

options taken from tippy.js docs

Contributors

| :---: |Michael Riess|