CngxPopover
projects/common/popover/popover.directive.ts
Import#
import { CngxPopover } from '@cngx/common/popover'
Description#
Signal-driven state machine for the native Popover API.
Wraps the browser's popover attribute with reactive state,
CSS-transition-aware lifecycle, and CSS Anchor Positioning.
Pure state machine - contains no trigger logic, no delays.
State lifecycle: closed → opening → open → closing → closed.
CSS classes cngx-popover--opening, cngx-popover--open, and
cngx-popover--closing are applied to the host for transition hooks.
Declarative click popover
<button [cngxPopoverTrigger]="pop" (click)="pop.toggle()">Menu</button>
<div cngxPopover #pop="cngxPopover" placement="bottom-start">
<menu><li>Edit</li><li>Delete</li></menu>
</div>Controlled open state
<div cngxPopover [cngxPopoverOpen]="showErrors()" role="alert">
{{ errorSummary() }}
</div>Collision recovery with <try-tactic> fallbacks
Apply CSS Anchor Positioning's position-try-fallbacks declaratively
by binding the new positionTryFallbacks input. Each entry is a CSS
<try-tactic> keyword (or composed pair) written verbatim into the
host's position-try-fallbacks property. Mirrors the precedent in
@cngx/forms/select panels.
<div cngxPopover
placement="right-start"
[positionTryFallbacks]="['flip-inline', 'flip-block', 'flip-block flip-inline']">
<!-- popover content -->
</div>When the array is empty (default), the host does not write a
position-try-fallbacks style - the browser positions the popover at
the declared placement regardless of viewport clipping.
Metadata#
Host#
Relationships
Used by13
Index#
Methods
Inputs
Derived State
HostBindings
HostListeners
Inputs#
Whether a pointerdown outside both the popover and its anchor (trigger)
dismisses it - menu / listbox light-dismiss. Opt-in (default false) so
existing manual-mode popovers keep full control; the anchor is excluded so
a click on the trigger toggles via the trigger's own handler instead of
being closed here and immediately reopened.
falseboolean | undefinedControlled open state. When set, drives the popover reactively.
undefined = uncontrolled (default).
undefined, { alias: 'cngxPopoverOpen', }When true (default), opening this popover closes any other open
CngxPopover instance. Set to false to allow multiple popovers
open simultaneously.
truePopoverModeNative popover mode. 'manual' for full control, 'auto' for browser light dismiss.
'manual'readonly PopoverPositionTryFallback[]CSS <try-tactic> fallbacks for position-try-fallbacks. Empty
array (default) means the host does not write the property at all.
Non-empty entries are written verbatim, comma-joined, in declaration
order. Spec-compatible vocabulary only (no cngx placement tokens).
[]Instance Properties#
HTMLElement | nullThe anchor element for Floating UI fallback positioning.
Set by CngxPopoverTrigger or CngxTooltip.
signal<HTMLElement | null>(null)unknownPublic read-only view of the arrow's inline-axis offset (<px> or
null before the first geometry read). Consumers projecting a
cngxPopoverArrow template use this to render their own glyph at
the same coordinate the default arrow ornament would.
this._arrowOffset.asReadonly()unknownHost ElementRef. Public for consumers that need to pass the
popover's native element to APIs expecting an ElementRef
(scroll observers, intersection observers, focus managers, …).
Notable consumer: injectRecycler({ scrollElement: pop.elementRef })
for @cngx/forms/select virtualisation - the popover IS the
scroll container when select-base.css's max-height + overflow-y
rules apply.
inject<ElementRef<HTMLElement>>(ElementRef)PopoverHaspopup | undefinedHint for the CngxPopoverTrigger's aria-haspopup value. Composers
such as CngxPopoverPanel write this signal so any trigger pointing
at the popover defaults to the right role without the consumer
having to set haspopup on every trigger element. Consumer-supplied
haspopup on the trigger still wins.
signal<PopoverHaspopup | undefined>(undefined)Methods#
HostBindings#
| Binding | Expression |
|---|---|
[attr.popover] | mode() |
[id] | id() |
[attr.aria-hidden] | !isVisible() |
[attr.data-arrow-placement] | resolvedEdge() |
[class.cngx-popover--opening] | isOpening() |
[class.cngx-popover--open] | isOpen() |
[class.cngx-popover--closing] | isClosing() |
[style.position-anchor] | cssAnchorRef() |
[style.position-try-fallbacks] | cssPositionTryFallbacks() |
[style.margin] | cssMargin() |
[style.--cngx-popover-arrow-offset] | arrowOffset() |
HostListeners#
| Event | Handler |
|---|---|
(toggle) | toggle() |