@teamhive/ngx-tooltip
TypeScript icon, indicating that this package has built-in type declarations

0.3.15 • Public • Published

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

    Option Type Default Description
    group string, number undefined specifies a group collection the tooltip should belong to. Actions can be applied to an entire group via the TooltipServiceTooltipService. This property is custom to NgxTooltip and does not have a tippy.js equivalent.
    a11y boolean true Short for accessibility - ensures the reference element can receive focus so the tooltip can be activated by keyboard navigation by adding tabindex="0" to the reference element.
    animateFill boolean true Determines if the background fill color should be animated. Disabled if arrow: true.
    allowHTML boolean true Determines if the tippy can have HTML content rendered inside of it. Make sure you are sanitizing any user data if rendering HTML to prevent XSS attacks.
    animation string "shift-away" The type of transition animation. Possible values: "shift-away", "shift-toward", "fade", "scale", "perspective"
    appendTo string, Element, Function document.body The element to append the tippy to. Specify the string "parent" to append it to the reference element's parent. You can also define a function that takes the reference element as an argument and returns a new element.
    aria string "describedby" The aria-* attribute applied to the reference element. Use either "describedby" or "labelledby". Use a falsy value null / false to prevent the attribute from being added.
    arrow boolean false Determines if an arrow should be added to the tippy pointing toward the reference element.
    arrowType string "sharp" Determines the arrow type. Possible values: "sharp", "round"
    boundary string, HTMLElement "scrollParent" The boundary that Popper.js' preventOverflow modifier adheres to. Possible values: "scrollParent", "window", "viewport", or an HTMLElement.
    content string, Element, Function "" The content of the tippy. Along with a string or element, you can use a function that takes the reference element as an argument and returns content.
    delay number, [show, hide] [0, 20] Delay in ms once a trigger event is fired before a tippy shows or hides. Specifying a number means both the show and hide delays are the same. Use null in the array to use the default value.
    duration number, [show, hide] [275, 250] Duration of the CSS transition animation in ms. Specifying a number means both the show and hide delays are the same. Use null in the array to use the default value.
    distance number 10 How far in pixels the tippy element is from the reference element. Only applies to a single axis and not to the parent popper element, see the offset option.
    flip boolean true Determines if the tippy flips so that it is placed within the viewport as best it can be if there is not enough room.
    flipBehavior string, string[] "flip" Determines the order of flipping, i.e. which placements to prefer if a certain placement cannot be used. Use an array such as ["bottom", "left"] to prefer the "left" placement if "bottom" is unavailable, instead of "top".
    flipOnUpdate boolean false Determines if the tippy should flip when necessary if its position updates while showing (for example, while scrolling, resize, or if the size of the tooltip changed).
    followCursor boolean, string false Determines if the tippy follows the user's mouse cursor while showing. Use the strings "vertical" or "horizontal" to only follow the cursor on a single axis. Use "initial" to place the tippy at the initial cursor position upon show, but prevent following it.
    hideOnClick boolean, string true Determines if the tippy should hide if a click event was fired outside of it (i.e. clicking on the reference or the body). For click-triggered tippys, using false will prevent the tippy from ever hiding once it is showing. To prevent clicks outside of the tippy from hiding it but still allow it to be toggled, use the string "toggle".
    ignoreAttributes boolean false Determines if data-tippy-* attributes on the reference element should be ignored. Increases performance if you enable it.
    inertia boolean false Determines if an inertial slingshot effect is applied to the CSS transition-timing-function.
    interactive boolean false Determines if the tippy is interactive, i.e. it can be hovered over or clicked without hiding.
    interactiveBorder number 2 Determines the size in pixels of the invisible border around a tippy which will prevent it from closing if the cursor left the element.
    interactiveDebounce number 0 Debounces the internal onMouseMove handler which determines when an interactive tippy should hide.
    lazy boolean true Determines if the positioning engine (powered by Popper.js) is created lazily. That is, it's only created when necessary upon showing the tippy for the first time. If you need to access the popperInstance synchronously after creation, set this to false. Please note that this decreases performance considerably.
    maxWidth number, string 350 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.
    multiple boolean false Determines if the reference element can have multiple tippys applied to it.
    offset number, string 0 Determines the offset of the tippy element. Unlike distance, it can work on both axes by using a string in the form "x, y", such as "50, 20". Avoid this option if using interactive: true.
    onHidden Function noop Lifecycle function invoked when the tippy has fully transitioned out.
    onHide Function noop Lifecycle function invoked when the tippy begins to transition out. You can cancel hiding by returning false from this lifecycle.
    onMount Function noop Lifecycle function invoked when the tippy has been mounted to the DOM.
    onShow Function noop Lifecycle function invoked when the tippy begins to transition in. You can cancel showing by returning false from this lifecycle.
    onShown Function noop Lifecycle function invoked when the tippy has fully transitioned in.
    placement string "top" 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.
    popperOptions object {} Specify custom Popper.js options. See the Popper.js documentation for more.
    role string "tooltip" Specifies the role attribute on the tippy element.
    showOnInit boolean false Determines if the tippy will be shown immediately once the instance is created. If using on page load, use sticky: true because the reference element can move around while the layout gets built by the browser after initialization (unless the layout is guaranteed to be static).
    size string "regular" Determines the size of the tippy, defined in CSS. Possible values: "small", "regular", "large"
    sticky boolean false Ensures the tippy stays stuck to its reference element if it moves around while showing. See the updateDuration option to change the transition duration between position updates.
    target string "" CSS selector string used for event delegation. See Event delegation for more information.
    theme string "dark" Themes added as classes (each separated by a space) to the tippy element's classList.
    touch boolean true Determines if the tippy displays on touch devices.
    touchHold boolean false 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. To prevent the mobile context menu from appearing, ensure the element cannot be selected using user-select: none; and/or prevent the default behavior for the contextmenu event.
    trigger string "mouseenter focus" 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.
    updateDuration number 0 The transition duration between position updates for the sticky and flipOnUpdate options.
    wait Function null A function that, when defined, will wait until you manually invoke the show() method when a tippy is triggered. It takes the tippy instance as the first argument, and the trigger event as the second argument.
    zIndex number 9999 Determines the z-index of the tippy.

    Contributors

    Michael Riess
    Michael Riess

    Package Sidebar

    Install

    npm i @teamhive/ngx-tooltip

    Weekly Downloads

    60

    Version

    0.3.15

    License

    MIT

    Unpacked Size

    373 kB

    Total Files

    33

    Last publish

    Collaborators

    • emrado
    • granttw
    • jpinkster
    • sbannigan
    • jgibson55