Popover

Overview

Popover displays rich content in a portal, triggered by a button. It can be controlled (@bind-Open) or uncontrolled (DefaultOpen), portals its content to document.body to escape overflow and stacking contexts, and stays anchored to the trigger (or an explicit Anchor), flipping and shifting to stay in view. Optional Modal mode traps focus and locks page scroll; otherwise focus still moves in on open and is restored to the trigger on close.

Anatomy

@using Navius.Primitives.Components.Popover

<NaviusPopover>
    <NaviusPopoverTrigger />
    <NaviusPopoverAnchor />

    <NaviusPopoverPortal>
        <NaviusPopoverBackdrop />
        <NaviusPopoverPositioner>
            <NaviusPopoverPopup>
                <NaviusPopoverTitle />
                <NaviusPopoverDescription />
                <NaviusPopoverArrow />
                <NaviusPopoverClose />
            </NaviusPopoverPopup>
        </NaviusPopoverPositioner>
    </NaviusPopoverPortal>
</NaviusPopover>

Root

Contains all the parts of a popover. Owns the open state and cascades a PopoverContext to the parts. Renders no DOM of its own.

Prop	Type	Default	Description
`Open`	`bool`	`false`	Controlled open state. Pair with `OpenChanged` (`@bind-Open`).
`OpenChanged`	`EventCallback<bool>`	-	Fires when the controlled `Open` value should change.
`DefaultOpen`	`bool`	`false`	Initial open state when used uncontrolled.
`Modal`	`bool`	`false`	When `true`, traps focus inside the popup and locks page scroll while open.
`ChildContent`	`RenderFragment?`	-	The popover’s parts.

Trigger

The button that toggles the popover and anchors its positioning. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Trigger label content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Anchor

An optional explicit positioning reference. When present, the content anchors to it instead of the trigger. Renders a div.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	The anchor’s content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Portal

Records a custom mount container and keep-mounted flag into the context; the Popup and Backdrop perform the actual teleport. Renders no DOM of its own.

Prop	Type	Default	Description
`Container`	`string?`	-	CSS selector for the mount target. `null` uses `document.body`.
`KeepMounted`	`bool`	`false`	Keeps the popup (and backdrop) mounted while closed, for exit animations.
`ChildContent`	`RenderFragment?`	-	The Positioner and Popup.

Backdrop

The dimming scrim, meaningful in Modal mode. Purely presentational; outside dismissal is owned by the Popup’s dismissable layer, not this element. Portaled to document.body, as a sibling of the Positioner. Renders a div.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the backdrop mounted while closed, for exit animations.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Positioner

Owns placement (side, align, offsets, collision). Publishes the placement options into the context; the Popup renders the actual positioning div. Renders no DOM of its own.

Prop	Type	Default	Description
`Side`	`string?`	`"bottom"`	Preferred side: `"top"` \| `"right"` \| `"bottom"` \| `"left"`.
`Align`	`string?`	`"center"`	Alignment along the side: `"start"` \| `"center"` \| `"end"`.
`SideOffset`	`double`	`0`	Distance in px from the anchor along the side.
`AlignOffset`	`double`	`0`	Offset in px along the alignment axis.
`Flip`	`bool`	`true`	Flip to the opposite side on collision.
`AvoidCollisions`	`bool`	`true`	Avoid collisions with the viewport boundary.
`CollisionPadding`	`double?`	-	Padding in px between the popup and the collision boundary.
`Sticky`	`string?`	-	Sticky behavior while scrolling: `"partial"` \| `"always"`.
`HideWhenDetached`	`bool`	`false`	Hide the popup (`data-anchor-hidden`) when the anchor is fully clipped or detached.
`ArrowPadding`	`double`	`0`	Padding in px between the arrow and the popup edges.
`ChildContent`	`RenderFragment?`	-	The Popup.

While mounted, the engine writes --anchor-width, --anchor-height, --available-width, --available-height, and --transform-origin (px / value) onto the Positioner element.

The floating panel, wrapped by the Positioner and dismissable on outside-press or Escape. Self-portals; renders a div with role="dialog".

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`OnOpenAutoFocus`	`EventCallback<NaviusOpenAutoFocusEventArgs>`	-	Fires when focus moves into the popup on open; cancelable.
`OnCloseAutoFocus`	`EventCallback<NaviusCloseAutoFocusEventArgs>`	-	Fires when focus returns to the trigger on close; cancelable.
`OnEscapeKeyDown`	`EventCallback<NaviusEscapeKeyDownEventArgs>`	-	Fires on `Escape`; cancelable.
`OnPointerDownOutside`	`EventCallback<NaviusPointerDownOutsideEventArgs>`	-	Fires on pointer-down outside the popup; cancelable.
`OnFocusOutside`	`EventCallback<NaviusFocusOutsideEventArgs>`	-	Fires when focus moves outside the popup; cancelable.
`OnInteractOutside`	`EventCallback<NaviusInteractOutsideEventArgs>`	-	Fires on any outside interaction; cancelable.
`ChildContent`	`RenderFragment?`	-	The popover’s content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Title

An accessible title for the popup. aria-labelledby on the Popup points here. Renders an h2.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Title content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `h2`.

Description

An optional accessible description for the popup. aria-describedby on the Popup points here. Renders a p.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Description content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `p`.

Arrow

An optional arrow pointing at the anchor, placed and rotated by the positioner. Renders an svg inside a span.

Prop	Type	Default	Description
`Width`	`double`	`10`	Arrow width in px.
`Height`	`double`	`5`	Arrow height in px.
`ChildContent`	`RenderFragment?`	-	Custom arrow content, in place of the default triangle.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `span`.

Close

A button inside the content that closes the popover. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Close button content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Data attributes

Part	Attribute	Description
Trigger	`data-popup-open`	Present while the popover is open.
Trigger	`data-pressed`	Present while the trigger button is pressed.
Anchor	`data-navius-popover-anchor`	Present on the anchor wrapper.
Backdrop	`data-open`	Present while open.
Backdrop	`data-closed`	Present while closing (through the exit transition).
Backdrop	`data-starting-style`	Present at the start of the open transition.
Backdrop	`data-ending-style`	Present at the start of the close transition.
Positioner	`data-side`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`.
Positioner	`data-align`	`"start"` \| `"center"` \| `"end"`.
Positioner	`data-anchor-hidden`	Present when `HideWhenDetached` and the anchor is fully clipped or detached.
Popup	`data-open`	Present while open.
Popup	`data-closed`	Present while closing (through the exit transition).
Popup	`data-starting-style`	Present at the start of the open transition.
Popup	`data-ending-style`	Present at the start of the close transition.
Popup	`data-side`	Mirrors the Positioner’s `data-side`.
Popup	`data-align`	Mirrors the Positioner’s `data-align`.
Arrow	`data-navius-popover-arrow`	Present on the arrow element.
Close	`data-navius-popover-close`	Present on the close button.

Keyboard interactions

Key	Behavior
`Space`	Opens or closes the popover when focus is on the trigger.
`Enter`	Opens or closes the popover when focus is on the trigger.
`Tab`	Moves focus to the next focusable element. Focus is trapped when `Modal`.
`Shift + Tab`	Moves focus to the previous focusable element, trapped within the content when `Modal`.
`Escape`	Closes the popover and returns focus to the trigger.

ARIA mechanism

The Trigger wires aria-haspopup="dialog", aria-expanded, and aria-controls pointing at the Popup’s id. The Popup renders role="dialog". aria-labelledby and aria-describedby on the Popup are wired only when a Title or Description part is mounted, so no dangling IDREF is emitted when they’re absent. On open, focus moves into the Popup; on close, it’s restored to the Trigger; Modal additionally traps focus inside the Popup and locks page scroll while open. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.