Navigation Menu

Overview

Navigation Menu is a collection of links for navigating websites, rendered as a <nav> landmark rather than a menu widget. It can be controlled (@bind-Value) or uncontrolled (DefaultValue); hover opens an item’s content after Delay and sweeping across triggers switches instantly while a panel is already open. It supports horizontal and vertical orientation, nested Sub menus, and an optional shared resizing Viewport.

Anatomy

@using Navius.Primitives.Components.NavigationMenu

<NaviusNavigationMenu>
    <NaviusNavigationMenuList>
        <NaviusNavigationMenuItem Value="item-1">
            <NaviusNavigationMenuTrigger />
            <NaviusNavigationMenuPortal>
                <NaviusNavigationMenuPositioner>
                    <NaviusNavigationMenuPopup>
                        <NaviusNavigationMenuArrow />
                        <NaviusNavigationMenuContent>
                            <NaviusNavigationMenuLink Href="#" />

                            @* Optional nested submenu. *@
                            <NaviusNavigationMenuSub>
                                <NaviusNavigationMenuList>
                                    <NaviusNavigationMenuItem Value="sub-1">
                                        <NaviusNavigationMenuTrigger />
                                        <NaviusNavigationMenuContent />
                                    </NaviusNavigationMenuItem>
                                </NaviusNavigationMenuList>
                            </NaviusNavigationMenuSub>
                        </NaviusNavigationMenuContent>
                    </NaviusNavigationMenuPopup>
                </NaviusNavigationMenuPositioner>
            </NaviusNavigationMenuPortal>
        </NaviusNavigationMenuItem>

        <NaviusNavigationMenuItem Value="item-2">
            <NaviusNavigationMenuLink Href="#" />
        </NaviusNavigationMenuItem>
    </NaviusNavigationMenuList>

    @* Optional shared resizing container. *@
    <NaviusNavigationMenuViewport />
</NaviusNavigationMenu>

Root

Contains all the parts of a navigation menu and owns the open value. Renders a nav.

Prop	Type	Default	Description
Value	string?	-	Controlled open value (the value of the open item, or null). Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string?>	-	Fires when the controlled Value should change.
DefaultValue	string?	-	Initial open value when used uncontrolled.
Orientation	string	"horizontal"	"horizontal" or "vertical".
Delay	int	50	Delay in ms before a hover opens an item’s content.
CloseDelay	int	50	Delay in ms before leaving the menu closes the open content.
OnOpenChangeComplete	EventCallback<bool>	-	Fires after the popup’s enter/exit presence settles, with the resulting open state.
ChildContent	RenderFragment?	-	The menu’s parts.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered nav.

List

The top-level list of items, aligned along the edge of the active content. Renders a ul.

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	The Item children.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered ul.

Item

A single list item holding either a Trigger + Content pair or a top-level Link. Renders an li.

Prop	Type	Default	Description
Value	string	""	The item’s value, matched against the root’s open value.
ChildContent	RenderFragment?	-	A Trigger + Content pair, or a Link.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered li.

Trigger

The button that discloses its item’s content. Renders a button.

Prop	Type	Default	Description
Disabled	bool	false	Disables the trigger.
NativeButton	bool	true	Renders a native <button type="button"> when true.
ChildContent	RenderFragment?	-	Trigger content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Portal

Optional wrapper that hoists the Popup to the portal target. 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 mounted while the menu is closed, for exit animations.
ChildContent	RenderFragment?	-	The Positioner and Popup.

Positioner

Owns placement (side / align / offsets / collision). Publishes the placement options to the Popup; renders no DOM of its own.

Prop	Type	Default	Description
Side	string	"bottom"	Preferred side.
Align	string	"center"	Alignment along the side.
SideOffset	double	0	Distance in px from the trigger 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.
HideWhenDetached	bool	false	Hide the popup when the trigger is fully clipped/detached.
ArrowPadding	double	0	Padding in px between the arrow and the popup edges.
ChildContent	RenderFragment?	-	The Popup.

Popup

The panel disclosed by a trigger. Self-anchors as a popover, or teleports into a Viewport when one is present. Renders a div.

Prop	Type	Default	Description
KeepMounted	bool	false	Keeps the popup mounted while closed, for exit animations.
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 Arrow and Content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Arrow

A marker inside the Popup that the positioner keeps pointed at the active trigger. Renders an svg.

Prop	Type	Default	Description
Width	double	10	Arrow width in px.
Height	double	5	Arrow height in px.
ChildContent	RenderFragment?	-	Custom arrow glyph (defaults to a triangle).
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered svg.

Content

The panel disclosed by a trigger. In standalone mode it is the Popup’s child; when a Viewport is present it teleports into the shared viewport slot instead. Renders a div.

Prop	Type	Default	Description
ForceMount	bool	false	Keeps the panel mounted while closed (data-closed), for external animation libraries.
ChildContent	RenderFragment?	-	Panel content (Links, a nested Sub).
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Link

A navigational anchor, used as a top-level item or inside a Content panel. Renders an a.

Prop	Type	Default	Description
Href	string?	-	The link target.
Active	bool	false	Marks this link as the active/current page.
OnSelect	EventCallback<NaviusSelectEventArgs>	-	Cancelable. Fires on activation; unless prevented, selecting a link closes the open disclosure.
ChildContent	RenderFragment?	-	Link content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered a.

Viewport

The shared resizing container that hosts the active panel. Place it outside the List; open Content teleports into it. Renders a div.

Prop	Type	Default	Description
ForceMount	bool	false	Accepted for prop parity; the container is always present.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

While open, the engine writes --navius-navigation-menu-viewport-width and --navius-navigation-menu-viewport-height (px) on the element so the container can animate to the active panel’s size.

Sub

A nested submenu root, placed inside a Content panel. Owns its own open value and orientation. Renders a div.

Prop	Type	Default	Description
Value	string?	-	Controlled open value (of the open sub-item, or null). Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string?>	-	Fires when the controlled Value should change.
DefaultValue	string?	-	Initial open value when used uncontrolled.
Orientation	string	"vertical"	"horizontal" or "vertical".
Delay	int	50	Delay in ms before a hover opens a sub-item’s content.
CloseDelay	int	50	Delay in ms before leaving closes the open sub-content.
ChildContent	RenderFragment?	-	The submenu’s List.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Data attributes

Part	Attribute	Description
Root	data-orientation	"horizontal" | "vertical"
List	data-popup-open	Present while any item’s content is open.
List	data-orientation	"horizontal" | "vertical"
Item	data-orientation	"horizontal" | "vertical"
Trigger	data-popup-open	Present while the item’s content is open.
Trigger	data-orientation	"horizontal" | "vertical"
Trigger	data-disabled	Present when disabled.
Popup	data-open	Present while open.
Popup	data-closed	Present while closing (through the exit transition).
Popup	data-activation-direction	"left" | "right" | "up" | "down", direction of the previously active item.
Popup	data-orientation	"horizontal" | "vertical"
Arrow	data-side	"top" | "right" | "bottom" | "left"
Content	data-open	Present while the item is active.
Content	data-closed	Present while closing (through the exit transition).
Content	data-activation-direction	"left" | "right" | "up" | "down", direction of the previously active item.
Content	data-orientation	"horizontal" | "vertical"
Link	data-active	Present when Active (also sets aria-current="page").
Viewport	data-orientation	"horizontal" | "vertical"
Sub	data-orientation	"horizontal" | "vertical"

Keyboard interactions

Key	Behavior
Space	When focus is on a trigger, toggles its content open or closed.
Enter	When focus is on a trigger, toggles its content open or closed.
ArrowDown	In horizontal orientation, opens the focused trigger’s content and moves focus into it.
ArrowRight	In vertical orientation, opens the focused trigger’s content and moves focus into it. In horizontal orientation, moves to the next trigger.
ArrowLeft	In horizontal orientation, moves focus to the previous trigger.
ArrowUp	In vertical orientation, moves focus to the previous trigger.
Home	Moves focus to the first trigger.
End	Moves focus to the last trigger.
Esc	Closes the open content and returns focus to its trigger.
Tab	Moves focus into the content, then out of the menu.

ARIA mechanism

The Root is a <nav> landmark, not a menu widget: the trigger row behaves as a single composite Tab stop with arrow-key roving. Each Trigger wires aria-expanded and aria-controls pointing at the popup it owns; each Popup wires aria-labelledby back to the id of its (currently active) Trigger; each Link sets aria-current="page" when Active. This implements the WAI-ARIA APG disclosure pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.