Popover

Display arbitrary content inside floating panels.

Import

Import the Popover primitives from ng-primitives/popover.

import { NgpPopover, NgpPopoverTrigger, NgpPopoverArrow } from 'ng-primitives/popover';

Usage

Assemble the popover directives in your template.

<button [ngpPopoverTrigger]="popover" (ngpPopoverTriggerOpenChange)="onPopoverStateChange($event)">
  Click me
</button>

<ng-template #popover>
  <div ngpPopover>Popover content</div>
</ng-template>

You can listen to the ngpPopoverTriggerOpenChange event to perform actions when the popover state changes. The event emits a boolean value indicating whether the popover is open or closed:

Reusable Component

Create a popover component that uses the NgpPopover directive.

API Reference

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

NgpPopover

Data Attributes

Attribute	Description
data-enter	Applied when the popover is being added to the DOM. This can be used to trigger animations.
data-exit	Applied when the popover is being removed from the DOM. This can be used to trigger animations.
data-placement	The final rendered placement of the popover.

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

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

NgpPopoverTrigger

Data Attributes

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

NgpPopoverArrow

The NgpPopoverArrow directive is used to add an arrow to the popover. It should be placed inside the popover content. It will receive inset-inline-start or inset-block-start styles to position the arrow based on the popover's placement. As a result it should be positioned absolutely within the popover content.

The arrow can be styled conditionally based on the popover's final placement using the data-placement attribute:

[ngpPopoverArrow][data-placement='top'] {
  /* Arrow styles when popover is positioned on top */
}

[ngpPopoverArrow][data-placement='bottom'] {
  /* Arrow styles when popover is positioned on bottom */
}

Data Attributes

Attribute	Description
data-placement	The final rendered placement of the popover.

Styling

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

[ngpPopover] {
  position: absolute;
}

Animations

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

The ngpPopover 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 popovers in your application by using the providePopoverConfig function in a providers array.

import { providePopoverConfig } from 'ng-primitives/popover';

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

NgpPopoverConfig

Define the offset from the trigger element. Define the placement of the popover. Define the delay before the popover shows. Define the delay before the popover hides. Define if the popover should flip when it reaches the edge of the viewport. Define the container element for the popover. This is the document body by default. Define whether the popover should close when clicking outside of it. Defines how the popover behaves when the window is scrolled. If set to `reposition`, the popover will adjust its position automatically during scrolling. Make sure the popover uses `position: absolute` in this mode. If set to `block`, scrolling will be disabled while the popover is open. In this case, the popover should use `position: fixed`.