Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mkeller1992/ngx-tooltip-directives
An Angular Tooltip Library
https://github.com/mkeller1992/ngx-tooltip-directives
Last synced: 2 months ago
JSON representation
An Angular Tooltip Library
- Host: GitHub
- URL: https://github.com/mkeller1992/ngx-tooltip-directives
- Owner: mkeller1992
- License: mit
- Created: 2023-05-22T15:43:38.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-05-18T20:53:36.000Z (8 months ago)
- Last Synced: 2024-05-22T07:47:25.689Z (8 months ago)
- Language: TypeScript
- Size: 2.64 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-angular - ngx-tooltip-directives - This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained <b><code> 100⭐</code></b> <b><code> 76🍴</code></b> [ng2-tooltip-directive](https://github.com/drozhzhin-n-e/ng2-tooltip-directive)). (Table of contents / Third Party Components)
- awesome-angular - ngx-tooltip-directives - This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained [ng2-tooltip-directive](https://github.com/drozhzhin-n-e/ng2-tooltip-directive). (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-tooltip-directives - This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained <b><code> 102⭐</code></b> <b><code> 76🍴</code></b> [ng2-tooltip-directive](https://github.com/drozhzhin-n-e/ng2-tooltip-directive)). (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-tooltip-directives - This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained <b><code> 101⭐</code></b> <b><code> 76🍴</code></b> [ng2-tooltip-directive](https://github.com/drozhzhin-n-e/ng2-tooltip-directive)). (Table of contents / Third Party Components)
README
# ngx-tooltip-directives
[](https://badge.fury.io/js/ngx-tooltip-directives)
[](https://codecov.io/gh/mkeller1992/ngx-tooltip-directives)
This library offers three different tooltip directives (string, html and template) and draws inspiration from the no longer maintained ng2-tooltip-directive.
The latest library version is compatible with **Angular 18**.
Tooltips are informative pop-up tips that appear when you hover over or click on an item, providing helpful additional information or guidance.
---
## Demo
https://mkeller1992.github.io/ngx-tooltip-directives/
---
## Install
To install the library, enter the following command in your console:
```
npm i ngx-tooltip-directives
```
## Setup
### For apps based on `Standalone Components`
Import the directives for the respective tooltips directly in your component:
```ts
import { TooltipHtmlDirective, TooltipStrDirective, TooltipTemplateDirective } from '@ngx-tooltip-directives';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss'],
standalone: true,
imports: [TooltipStrDirective, TooltipHtmlDirective, TooltipTemplateDirective]
})
```
### For apps based on `ngModule`
Make sure you import `NgxTooltipDirectivesModule` into your `@NgModule`:
```ts
import { NgxTooltipDirectivesModule } from 'ngx-tooltip-directives';
@NgModule({
imports: [ NgxTooltipDirectivesModule ]
})
```
## Usage
There are three ways of creating a tooltip:
### Pass the tooltip text as a string via `tooltipStr`:
```html
Show Tooltip
```
### Pass the tooltip content as SafeHtml via `tooltipHtml`:
```html
Show Html Tooltip
```
```ts
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
// Code skipped for brevity
export class AppComponent {
rawHtml: string = '
This is a tooltip with HTML
';
safeTooltipHtml: SafeHtml;
constructor(private sanitizer: DomSanitizer){
this.safeTooltipHtml = this.sanitizer.bypassSecurityTrustHtml(this.rawHtml);
}
}
```
### Pass the tooltip content as template via `tooltipTemplate`:
```html
Tooltip Template
Show Tooltip Template
```
---
## Trigger tooltip programmatically
```html
show() via component.ts
hide() via component.ts
```
```ts
@ViewChild('myTooltip')
tooltip!: TooltipStrDirective;
show() {
this.tooltip.show();
}
hide() {
this.tooltip.hide();
}
```
---
## 3 ways of setting tooltip options
1 - Options can be set via html-attributes, so they have the highest priority:
```html
Show Tooltip
```
2 - Options can be passed to the tooltips as TooltipOptions object:
```html
Show Tooltip
```
```ts
myOptions: TooltipOptions = {
'placement': 'right',
'showDelay': 500
}
```
3 - Options can be set globally when importing the module:
For apps based on `Standalone Components`:
```ts
import { NgxTooltipDirectivesModule, TooltipOptions } from 'ngx-tooltip-directives';
const myDefaultTooltipOptions: TooltipOptions = {
'backgroundColor': 'yellow'
}
bootstrapApplication(AppComponent, {
providers: [
importProvidersFrom(
NgxTooltipDirectivesModule.forRoot(myDefaultTooltipOptions)
)
]
}).catch(err => console.error(err));
```
For apps based on `ngModule's`:
```ts
import { NgxTooltipDirectivesModule, TooltipOptions } from 'ngx-tooltip-directives';
const myDefaultTooltipOptions: TooltipOptions = {
'backgroundColor': 'yellow'
}
@NgModule({
imports: [
NgxTooltipDirectivesModule.forRoot(myDefaultTooltipOptions)
]
})
```
---
## Properties
| name | type | default | description |
|-----------------------|---------------------------------------|---------|-------------|
| id | string \| number | 0 | A custom id that can be assigned to the tooltip. |
| placement | Placement | 'top' | The position of the tooltip. |
| autoPlacement | boolean | true | If true, the tooltip will be placed so that it does not go beyond the borders of the browser window. |
| contentType | ContentType | 'string'| The type of content passed to the tooltip. |
| textColor | string | 'black' | The color of the tooltip text. |
| backgroundColor | string | 'white' | The background color of the tooltip. |
| borderColor | string | 'blue' | The border color of the tooltip. |
| textAlign | "left" \| "center" \| "right" | 'center'| The horizontal alignment of the tooltip text. |
| padding | string | '10px 13px 10px 13px' | The padding around the tooltip text (top, right, bottom, left). |
| shadow | boolean | true | If true, the tooltip will have a shadow. |
| showDelay | number | 0 | The delay in ms before the tooltip is shown. |
| hideDelay | number | 0 | The delay in ms before the tooltip is removed. |
| hideDelayTouchscreen | number | 0 | The delay in ms before the tooltip is hidden on mobile devices. |
| zIndex | number | 0 | The z-index of the tooltip. |
| animationDuration | number | 100 | The duration in ms that the animation takes to run from start to finish. |
| trigger | "hover" \| "click" | 'hover' | Specifies how the tooltip is triggered. The closing time is controlled with "hide-delay". |
| tooltipClass | string | '' | Any additional classes to be passed to the tooltip (target them with `::ng-deep`). |
| display | boolean | true | If true, the tooltip is available for display. |
| displayTouchscreen | boolean | true | If true, the tooltip will be displayed on mobile devices. |
| offset | number | 8 | The offset of the tooltip relative to the item. |
| maxWidth | string | '200px' | The maximum width of the tooltip. |
| hideDelayAfterClick | number | 0 | The delay in ms before hiding the tooltip when the "click" trigger is used. |
| pointerEvents | "auto" \| "none" | 'auto' | Defines whether or not the tooltip reacts to pointer events. |
| position | {top: number, left: number} | undefined | The coordinates of the tooltip relative to the browser window. |
---
## Events
Events are called in accordance with the delays specified in the options within the directive. By default, there is a no delay before the tooltip hides.
| Event | Description |
|------------------|---------------------------------------------------------------------------------------------|
| {type: "show", position: { top: number; left: number; } | DOMRect } | This event is fired prior to the tooltip's appearance. |
| {type: "shown", position: { top: number; left: number; } | DOMRect} | This event is fired following the tooltip's appearance animation. |
| {type: "hide", position: { top: number; left: number; } | DOMRect} | This event is fired prior to the tooltip being hidden. |
| {type: "hidden", position: { top: number; left: number; } | DOMRect} | This event is fired after the tooltip hiding animation completes. |
---
## Methods
If you have defined the directive options, these will be taken into consideration when calling the methods. This includes the delay before the tooltip appears and before it hides.
| Method | Description |
|------------------|---------------------------------------------------------------------------------------------|
| show() | Displays the tooltip. |
| hide() | Hides the tooltip. |
---
## Testing with NgxTooltipDirectives
To simplify unit testing of components that use `NgxTooltipDirectives`, this library provides a set of mock directives as well as a mock module. You can use these mocks to bypass the actual directive behavior in your tests, focusing on the component logic instead.
### Mocking when component under test is a standalone component
In the test initialization you might have to use `.overrideComponent` in order to override the actual directives with the mock-directives that are provided by my library.
```typescript
import { TestBed } from "@angular/core/testing";
import { DomSanitizer } from "@angular/platform-browser";
import { MockTooltipHtmlDirective, MockTooltipStrDirective, MockTooltipTemplateDirective,
TooltipHtmlDirective, TooltipStrDirective, TooltipTemplateDirective } from "@ngx-tooltip-directives";
import { AppComponent } from "./app.component";
describe("AppComponent", () => {
beforeEach(async () => {
await TestBed.configureTestingModule({
imports: [ AppComponent ],
providers: [
{ provide: DomSanitizer, useValue: { bypassSecurityTrustHtml: () => {} } },
]
})
.overrideComponent(AppComponent, {
remove: {
imports: [
TooltipStrDirective,
TooltipHtmlDirective,
TooltipTemplateDirective
]
},
add: {
imports: [
MockTooltipStrDirective,
MockTooltipHtmlDirective,
MockTooltipTemplateDirective
]
}
})
.compileComponents();
});
// Your tests here
});
```
### Mocking when component under test is a NgModule-based component
Import `MockNgxTooltipDirectivesModule` in your test suite's TestBed configuration:
```typescript
import { TestBed } from '@angular/core/testing';
import { AppComponent } from './app.component';
import { MockNgxTooltipDirectivesModule } from '@ngx-tooltip-directives';
describe('AppComponent', () => {
beforeEach(async () => {
await TestBed.configureTestingModule({
declarations: [AppComponent],
imports: [MockNgxTooltipDirectivesModule]
}).compileComponents();
});
// Your tests here
});
```