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

Obligatory Angular Project Stuff

Generated with Angular CLI version 7.3.0.

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

⚠️ Build ngx-tooltip Library

Any changes made to the ngx-tooltip library will not take affect until it is built.

Run npm run build:ngx-tooltip The library build artifacts will be stored in the dist/ngx-tooltip directory. Additionally, any styles in the projects/ngx-tooltip/assets/styles directory will be copied to dist/ngx-tooltip/assets/styles.

Code scaffolding

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

Contributors


Michael Riess

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
e2e		e2e
projects/ngx-tooltip		projects/ngx-tooltip
src		src
.gitignore		.gitignore
README.md		README.md
angular.json		angular.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tslint.json		tslint.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NgxTooltip

Install

Getting Started

Usage

Basic

HTML Content

Specify Options

TooltipService

Properties

Methods

Theming

CSS Variables

All Options

Obligatory Angular Project Stuff

Development server

Build

⚠️ Build ngx-tooltip Library

Code scaffolding

Running unit tests

Running end-to-end tests

Further help

Contributors

About

Releases 1

Packages

Contributors 2

Languages

TeamMaestro/ngx-tooltip

Folders and files

Latest commit

History

Repository files navigation

NgxTooltip

Install

Getting Started

Usage

Basic

HTML Content

Specify Options

TooltipService

Properties

Methods

Theming

CSS Variables

All Options

Obligatory Angular Project Stuff

Development server

Build

⚠️ Build ngx-tooltip Library

Code scaffolding

Running unit tests

Running end-to-end tests

Further help

Contributors

About

Resources

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Languages

Packages