@ngneat/helipopper
    TypeScript icon, indicating that this package has built-in type declarations

    5.1.1 • Public • Published


    MIT commitizen PRs styled with prettier All Contributors ngneat spectator @ngneat/helipopper

    A Powerful Tooltip and Popover for Angular Applications

    Tippy.js is the complete tooltip, popover, dropdown, and menu solution for the web, powered by Popper.js.

    It is an abstraction over Popper that provides the logic and optionally the styling involved in all types of elements that pop out from the flow of the document and get overlaid on top of the UI, positioned next to a reference element.

    This is a lightweight wrapper with additional features that lets you use it declaratively in Angular. Tippy has virtually no restrictions over Popper and gives you limitless control while providing useful behavior and defaults.

    If you're using v1 and don't want to migrate, you can find it here.

    Features

    Position Tooltips, Menus, Dropdowns, and Popovers
    Predefined Variations
    TemplateRef/Component Support
    Lazy Registration
    Manual Trigger Support
    Text Overflow Support
    Context Menu Support

    Installation

    npm install @ngneat/helipopper @ngneat/overview
    

    It will automatically add the TippyModule to your AppModule. You can configure it as shown below:

    import { TippyModule, tooltipVariation, popperVariation } from '@ngneat/helipopper';
    
    @NgModule({
      declarations: [AppComponent],
      imports: [TippyModule.forRoot({
        defaultVariation: 'tooltip',
        variations: {
          tooltip: tooltipVariation,
          popper: popperVariation,
        }
      })],
      bootstrap: [AppComponent]
    })
    export class AppModule {
    }

    Add the styles you want to styles.scss:

    @import '~tippy.js/dist/tippy.css';
    @import '~tippy.js/themes/light.css';
    @import '~tippy.js/animations/scale.css';

    You have the freedom to customize it if you need to.

    Now you can use it in your templates:

    <button tippy="Helpful Message">
      I have a tooltip
    </button>

    The library exposes default variations for tooltip and popper. You can use them, extend them, or pass your own variations. A variation is a set of predefined tippy properties. For example, here's how the built-in tooltip variation looks like:

    export const tooltipVariation = {
      theme: null,
      arrow: false,
      animation: 'scale',
      trigger: 'mouseenter',
      offset: [0, 5]
    };

    Use TemplateRef as content

    <button [tippy]="tpl" variation="popper">
      Click Me
    </button>
    
    <ng-template #tpl let-hide>
      <h6>Popover title</h6>
      <p>And here's some amazing content. It's very engaging. Right?</p>
    </ng-template>

    Use Component as content

    import { TIPPY_REF, TippyInstance } from '@ngneat/helipopper';
    
    @Component()
    class MyComponent {
      constructor(@Inject(TIPPY_REF) tippy: TippyInstance) {
      }
    }
    <button [tippy]="MyComponent">
      Click Me
    </button>

    Text Overflow

    You can pass the onlyTextOverflow input to show the tooltip only when the host overflows its container:

    <div style="max-width: 100px;" class="overflow-hidden flex">
      <p class="ellipsis" [tippy]="text" placement="right" [onlyTextOverflow]="true">
        {{ text }}
      </p>
    </div>

    Note that it's using ResizeObserver api.

    Lazy

    You can pass the lazy input when you want to defer the creation of tippy only when the element is in the view:

    <div *ngFor="let item of items" 
         [tippy]="item.label" 
         [lazy]="true">{{ item.label }}
    </div>

    Note that it's using IntersectionObserver api.

    Context Menu

    First, define the contextMenu variation:

    import { 
      popperVariation, 
      TippyModule, 
      tooltipVariation, 
      withContextMenuVariation 
    } from '@ngneat/helipopper';
    
    @NgModule({
      imports: [
        TippyModule.forRoot({
          defaultVariation: 'tooltip',
          variations: {
            tooltip: tooltipVariation,
            popper: popperVariation,
            contextMenu: withContextMenuVariation(popperVariation),
          }
        })
      ],
    })
    export class AppModule {}

    Now you can use it in your template:

    <ng-template #contextMenu let-hide let-item="data">
      <ul>
        <li (click)="copy(item); hide()">Copy</li>
        <li (click)="duplicate(item); hide()">Duplicate</li>
      </ul>
    </ng-template>
    
    <ul>
      <li *ngFor="let item of list" 
          [tippy]="contextMenu" 
          [data]="item" 
          variation="contextMenu">
        {{ item.label }}
      </li>
    </ul>

    Manual Trigger

    <div tippy="Helpful Message" trigger="manual" #tooltip="tippy">
      Click Open to see me
    </div>
    
    <button (click)="tooltip.show()">Open</button>
    <button (click)="tooltip.hide()">Close</button>

    Show/hide declarativly

    Use isVisible to trigger show and hide. Set trigger to manual.

    <div tippy="Helpful Message" trigger="manual" [isVisible]="visibility">
      Click Open to see me
    </div>
    
    <button (click)="visibility = true">Open</button>
    <button (click)="visibility = false">Close</button>

    You can see more examples in our playground, or live here.

    Inputs

    appendTo: TippyProps['appendTo'];
    delay: TippyProps['delay'];
    duration: TippyProps['duration'];
    hideOnClick: TippyProps['hideOnClick'];
    interactive: TippyProps['interactive'];
    interactiveBorder: TippyProps['interactiveBorder'];
    maxWidth: TippyProps['maxWidth'];
    offset: TippyProps['offset'];
    placement: TippyProps['placement'];
    popperOptions: TippyProps['popperOptions'];
    showOnCreate: TippyProps['showOnCreate'];
    trigger: TippyProps['trigger'];
    triggerTarget: TippyProps['triggerTarget'];
    zIndex: TippyProps['zIndex'];
    tippyHost: HTMLElement;
    
    lazy: boolean;
    variation: string;
    isEnabled: boolean;
    isVisible: boolean;
    className: string;
    onlyTextOverflow: boolean;
    useHostWidth: boolean;
    hideOnEscape: boolean;
    data: any;

    Outputs

    visible = new EventEmitter<boolean>();

    Global Config

    • You can pass any tippy option at global config level.
    • beforeRender - Hook that'll be called before rendering the tooltip content ( applies only for string )

    Create tippy Programmatically

    import { TippyService, TippyInstance } from '@ngneat/helipopper';
    
    class Component {
      @ViewChild('inputName') inputName: ElementRef;
      private tippy: TippyInstance;
    
      constructor(private tippy: TippyService) {
      }
    
      open() {
        if(!this.tippy) {
          this.tippy = this.tippy.create(this.inputName, 'this field is required');
        }
    
        this.tippy.open();
      }
    
      ngOnDestroy() {
        this.tippy?.destroy();
      }
    }

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Netanel Basal

    💻 📖 🤔

    Itay Oded

    💻

    Gérôme Grignon

    💻

    Artur Androsovych

    💻 ⚠️

    Shahar Kazaz

    💻 📖

    stefanoww

    💻

    Ryan Hutchison

    💻 📖 🤔

    This project follows the all-contributors specification. Contributions of any kind welcome! Icon made by Airport from www.flaticon.com

    Install

    npm i @ngneat/helipopper

    DownloadsWeekly Downloads

    3,831

    Version

    5.1.1

    License

    MIT

    Unpacked Size

    205 kB

    Total Files

    22

    Last publish

    Collaborators

    • netanel-ngneat
    • itayod
    • shahar.kazaz
    • ggrignon