Primitives

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:

Examples

Custom Offset

You can customize the offset using either a simple number or an object for more precise control:

<!-- Simple number offset -->
<button [ngpPopoverTrigger]="popover" ngpPopoverTriggerOffset="12">Popover with 12px offset</button>

<!-- Object offset for precise control -->
<button
  [ngpPopoverTrigger]="popover"
  [ngpPopoverTriggerOffset]="{mainAxis: 8, crossAxis: 4, alignmentAxis: 2}"
>
  Popover with custom offset
</button>

Reusable Component

Create a popover component that uses the NgpPopover directive.

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

@Component({
  selector: 'app-root',
  imports: [NgpButton, PopoverTrigger],
  template: `
    <button ngpButton appPopoverTrigger="Popover content">Popover</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 {}

API Reference

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

NgpPopover

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

  • Selector: [ngpPopover]
  • Exported As: 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

Apply the `ngpPopoverTrigger` directive to an element that triggers the popover to show.

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

Access the popover template ref.

ngpPopoverTriggerDisabled
boolean
default: "false"

Define if the trigger should be disabled.

ngpPopoverTriggerPlacement
NgpPopoverPlacement
default: "'top'"

Define the placement of the popover relative to the trigger.

ngpPopoverTriggerOffset
NgpOffset
default: "0"

Define the offset of the popover relative to the trigger. Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis.

ngpPopoverTriggerShowDelay
number
default: "0"

Define the delay before the popover is displayed.

ngpPopoverTriggerHideDelay
number
default: "0"

Define the delay before the popover is hidden.

ngpPopoverTriggerFlip
boolean
default: "true"

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

ngpPopoverTriggerContainer
string | HTMLElement | null
default: "document.body"

Define the container in which the popover should be attached.

ngpPopoverTriggerCloseOnOutsideClick
boolean
default: "true"

Define whether the popover should close when clicking outside of it.

ngpPopoverTriggerCloseOnEscape
boolean
default: "true"

Define whether the popover should close when the escape key is pressed.

ngpPopoverTriggerScrollBehavior
"block" | "reposition"
default: "'reposition'"

Defines how the popover behaves when the window is scrolled.

ngpPopoverTriggerContext
T | undefined

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

ngpPopoverTriggerOpenChange
boolean

Event emitted when the popover open state changes.

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 */
}

  • Selector: [ngpPopoverArrow]
  • Exported As: ngpPopoverArrow

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

offset
number | NgpOffsetOptions

Define the offset from the trigger element. Can be a number (applies to mainAxis) or an object with mainAxis, crossAxis, and alignmentAxis properties.

Number format: offset: 8 - Applies to mainAxis (distance from trigger)

Object format: 

offset: {
  mainAxis: 8,     // Distance between popover and trigger element
  crossAxis: 4,    // Skidding along the alignment axis  
  alignmentAxis: 2 // Same as crossAxis but for aligned placements
}

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

Define the placement of the popover.

showDelay
number

Define the delay before the popover shows.

hideDelay
number

Define the delay before the popover hides.

flip
boolean

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

container
HTMLElement

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

closeOnOutsideClick
boolean

Define whether the popover should close when clicking outside of it.

scrollBehavior
reposition | block

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

Copyright © 2025 Angular Primitives