Primitives

Tooltip

Display additional information on hover.

Import

Import the Tooltip primitives from ng-primitives/tooltip.

import { NgpTooltip, NgpTooltipTrigger } from 'ng-primitives/tooltip';

Usage

Assemble the tooltip directives in your template.

<button [ngpTooltipTrigger]="tooltip" ngpButton>Hover me</button>

<ng-template #tooltip>
  <div ngpTooltip>Tooltip content</div>
</ng-template>

Reusable Component

Create a tooltip component that uses the NgpTooltip directive.

import { Component } from '@angular/core';
import { NgpButton } from 'ng-primitives/button';
import { TooltipTrigger } from './tooltip-trigger';

@Component({
  selector: 'app-root',
  imports: [TooltipTrigger, NgpButton],
  template: `
    <button ngpButton appTooltipTrigger="Tooltip content here">Show tooltip</button>
  `,
  styles: `
    [ngpButton] {
      padding-left: 1rem;
      padding-right: 1rem;
      border-radius: 0.5rem;
      color: var(--ngp-text-primary);
      outline: none;
      height: 2.5rem;
      font-weight: 500;
      border: none;
      background-color: var(--ngp-background);
      transition: background-color 300ms cubic-bezier(0.4, 0, 0.2, 1);
      box-shadow: var(--ngp-button-shadow);
    }

    [ngpButton][data-hover] {
      background-color: var(--ngp-background-hover);
    }

    [ngpButton][data-focus-visible] {
      outline: 2px solid var(--ngp-focus-ring);
    }

    [ngpButton][data-press] {
      background-color: var(--ngp-background-active);
    }
  `,
})
export default class App {}

Schematics

Generate a reusable tooltip component using the Angular CLI.

ng g ng-primitives:primitive tooltip

Options

  • path: The path at which to create the component file.
  • prefix: The prefix to apply to the generated component selector.
  • componentSuffix: The suffix to apply to the generated component class name.
  • fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
  • exampleStyles: Whether to include example styles in the generated component file. Defaults to true.

API Reference

The following directives are available to import from the ng-primitives/tooltip package:

NgpTooltip

Apply the `ngpTooltip` directive to an element that represents the tooltip. This typically would be a `div` inside an `ng-template`.

  • Selector: [ngpTooltip]
  • Exported As: ngpTooltip

Data Attributes

Attribute Description
data-enter Applied when the tooltip is being added to the DOM. This can be used to trigger animations.
data-exit Applied when the tooltip is being removed from the DOM. This can be used to trigger animations.

The following CSS custom properties are applied to the ngpTooltip directive:

Property Description
--ngp-tooltip-transform-origin The transform origin of the tooltip for animations.
--ngp-tooltip-trigger-width The width of the trigger element.

NgpTooltipTrigger

Apply the `ngpTooltipTrigger` directive to an element that triggers the tooltip to show.

  • Selector: [ngpTooltipTrigger]
  • Exported As: ngpTooltipTrigger
ngpTooltipTrigger
NgpOverlayContent<T> | undefined

Access the tooltip template ref.

ngpTooltipTriggerDisabled
boolean
default: "false"

Define if the trigger should be disabled.

ngpTooltipTriggerPlacement
Placement
default: "'top'"

Define the placement of the tooltip relative to the trigger.

ngpTooltipTriggerOffset
number
default: "0"

Define the offset of the tooltip relative to the trigger.

ngpTooltipTriggerShowDelay
number
default: "0"

Define the delay before the tooltip is displayed.

ngpTooltipTriggerHideDelay
number
default: "0"

Define the delay before the tooltip is hidden.

ngpTooltipTriggerFlip
boolean
default: "true"

Define whether the tooltip should flip when there is not enough space for the tooltip.

ngpTooltipTriggerContainer
HTMLElement | null
default: "document.body"

Define the container in which the tooltip should be attached.

ngpTooltipTriggerContext
T | undefined

Provide context to the tooltip. This can be used to pass data to the tooltip content.

Data Attributes

Attribute Description
data-open Applied when the tooltip is open.
data-disabled Applied when the tooltip is disabled.

Styling

For the tooltip to be positioned correctly relative to the trigger element, it must use absolute or fixed positioning. For example, you can use the following CSS:

[ngpTooltip] {
  position: absolute;
}

Animations

The ngpTooltip primitive adds a CSS custom property --ngp-tooltip-transform-origin to the element that can be used to animate the tooltip from the trigger element.

The ngpTooltip will also add the data-enter and data-exit attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}

Global Configuration

You can configure the default options for all tooltips in your application by using the provideTooltipConfig function in a providers array.

import { provideTooltipConfig } from 'ng-primitives/tooltip';

bootstrapApplication(AppComponent, {
  providers: [
    provideTooltipConfig({
      offset: 4,
      placement: 'top',
      showDelay: 0,
      hideDelay: 0,
      flip: true,
      container: document.body,
    }),
  ],
});

NgpTooltipConfig

offset
number

Define the offset from the trigger element.

placement
'top' | 'right' | 'bottom' | 'left'

Define the placement of the tooltip.

showDelay
number

Define the delay before the tooltip shows.

hideDelay
number

Define the delay before the tooltip hides.

flip
boolean

Define if the tooltip should flip when it reaches the edge of the viewport.

container
HTMLElement

Define the container element for the tooltip. This is the document body by default.

Copyright © 2025 Angular Primitives