Popover
Arbitrary Angular content in a non-modal, trigger-anchored top layer with viewport-aware placement and deterministic focus restoration.
GET STARTED
Import
Import only the standalone primitive and directives used by the template.
Account panel
The trigger owns disclosure semantics while Popover owns state, positioning, dismissal and restoration.
Logical positions
Start and end follow writing direction. The shared positioner flips and clamps the panel inside the viewport.
Controlled state
Two-way bind the Signal model when application state must remain authoritative.
Focus workflow
Focus remains on the trigger by default. Interactive disclosures can explicitly focus the first meaningful field.
Dismiss policy
Outside pointer and Escape dismissal are independent. A close directive provides an explicit path.
Trigger width
matchTriggerWidth keeps select-like disclosure surfaces aligned without measuring in consumer code.
Unstyled and typed slots
All behavior and structural hooks remain while Tailwind owns the visual layer.
Consumer-owned surface
Semantics, positioning and dismissal remain intact.
ACCESSIBILITY
Non-modal by design
Popover preserves native disclosure behavior without inventing menu semantics or trapping focus.
Trigger contract
Use a native interactive trigger. The directive synchronizes aria-controls and aria-expanded.
Roles and labels
dialog and region are opt-in because arbitrary disclosure content needs no universal role. Name either role through ariaLabel or ariaLabelledby.
Focus lifecycle
Default opening keeps trigger focus. Explicit and Escape closes restore it; outside pointer dismissal preserves the newly selected target.
Keyboard
Enter or Space activates a native button trigger. Escape closes only the topmost eligible Popover.
Top layer and RTL
Native Popover avoids clipping, so no appendTo="body" input is needed. Logical start/end placements mirror under RTL.
SSR and hydration
The server renders deterministic closed markup. Top-layer and positioner work begins only in the browser.
PUBLIC CONTRACT
Popover API
Component inputs
| Input | Type | Default | Purpose |
|---|---|---|---|
| open | ModelSignal<boolean> | false | Controlled visibility state. |
| position | NeuralPopoverPosition | 'bottom-start' | Fallback logical placement. |
| offset | number | 8 | Gap from the active trigger in pixels. |
| viewportPadding | number | 8 | Minimum distance from viewport edges. |
| focusOnOpen | 'none' | 'first' | 'none' | Optional focus transfer policy. |
| dismissible | boolean | true | Closes on outside pointer interaction. |
| closeOnEscape | boolean | true | Closes the topmost panel with Escape. |
| restoreFocus | boolean | true | Returns focus for explicit and keyboard closes. |
| matchTriggerWidth | boolean | false | Matches the active trigger inline size. |
| showArrow | boolean | false | Renders the positioned structural arrow. |
| role | 'dialog' | 'region' | null | null | Opt-in semantic role. |
| popoverId | string | generated | Stable ID linked to the trigger. |
| ariaLabel | string | null | null | Direct accessible name. |
| ariaLabelledby | string | null | null | Visible accessible-name reference. |
| ariaDescribedby | string | null | null | Accessible description reference. |
| unstyled | boolean | false | Removes NeuralNg visual classes. |
| popoverClass | string | '' | Additive root classes. |
| classes | NeuralPopoverClasses | {} | Typed root, content and arrow slots. |
Trigger inputs
| neuralPopoverTriggerFor | NeuralPopover | required | Popover instance controlled by this trigger. |
| popoverPosition | NeuralPopoverPosition | component value | Per-trigger placement override. |
| popoverOffset | number | component value | Per-trigger gap override. |
| popoverViewportPadding | number | component value | Per-trigger viewport padding. |
| popoverFocusOnOpen | 'none' | 'first' | component value | Per-trigger focus policy. |
| popoverDisabled | boolean | false | Disables disclosure behavior. |
Outputs
openChangebooleanGenerated by the open model.
openedNeuralPopoverOpenEventActive trigger and requested position.
closedNeuralPopoverCloseEventExact reason, trigger and original event.
Imperative methods
showFor(trigger, options?)→ voidOpens for a specific HTMLElement.
toggleFor(trigger, options?, event?)→ voidToggles for a specific trigger.
hide(reason?, restoreFocus?, event?)→ voidCloses with deterministic metadata.
isTriggerOpen(trigger)→ booleanChecks whether a trigger owns the open panel.
Directives
NeuralPopoverTriggerDisclosure and ARIA synchronization.
NeuralPopoverCloseExplicit in-panel close action.
NeuralPopoverInitialFocusPreferred initial focus target.
Typed class slots
rootTop-layer positioned panel.
contentProjected content wrapper.
arrowOptional positioned arrow.
Public types
NeuralPopoverPosition'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'right'
NeuralPopoverCloseReason'trigger' | 'outside' | 'escape' | 'close-directive' | 'api' | 'native'
NeuralPopoverClasses{ root?, content?, arrow? }
NeuralPopoverShowOptions{ position?, offset?, viewportPadding?, focusOnOpen? }
Legacy aliases
PopoverComponent, PopoverTriggerDirective, PopoverCloseDirective and PopoverInitialFocusDirective remain compatible. New code should use the concise Neural-prefixed exports.
DESIGN TOKENS
Popover tokens
Component-scoped custom properties preserve theme ownership without closing the headless escape hatch.
Sizing
--neural-popover-widthComponent inline size.
--neural-popover-min-widthComponent minimum inline size.
--neural-popover-max-widthComponent maximum inline size.
--neural-popover-max-heightComponent maximum block size.
--neural-popover-paddingComponent internal spacing.
Surface
--neural-popover-colorComponent foreground color.
--neural-popover-backgroundComponent background surface.
--neural-popover-borderComponent border shorthand.
--neural-popover-radiusComponent corner radius.
--neural-popover-shadowComponent box shadow.
--neural-popover-font-familyComponent font family.
Arrow
--neural-popover-arrow-sizeArrow width and height.
--neural-popover-arrow-backgroundArrow background surface.
--neural-popover-arrow-borderArrow border shorthand.
--neural-popover-arrow-offsetArrow positional offset.
Motion
--neural-popover-enter-durationComponent enter animation duration.
--neural-popover-leave-durationComponent leave animation duration.
--neural-popover-enter-distanceComponent enter animation travel distance.
--neural-popover-enter-scaleComponent enter animation starting scale.
--neural-popover-easingComponent animation easing curve.