Primitives

Popover

Display arbitrary content inside floating panels.

Import

Import the Popover primitives from ng-primitives/popover.

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

Usage

Assemble the popover directives in your template.

<button [ngpPopoverTrigger]="popover">Click me</button>

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

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

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
Placement
default: "'top'"

Define the placement of the popover relative to the trigger.

ngpPopoverTriggerOffset
number
default: "0"

Define the offset of the popover relative to the trigger.

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

Data Attributes

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

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

Define the offset from the trigger element.

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