Context Menu

Overview

Context Menu displays a menu located at the pointer, triggered by a right click or a long press. It is anchored to the pointer position with collision-aware flipping and clamping, supports submenus with configurable reading direction, and provides items, labels, groups, checkbox items, and radio groups with full keyboard navigation (roving focus and type-ahead).

Anatomy

@using Navius.Primitives.Components.ContextMenu

<NaviusContextMenu>
    <NaviusContextMenuTrigger />

    <NaviusContextMenuPositioner>
        <NaviusContextMenuPopup>
            <NaviusContextMenuLabel />
            <NaviusContextMenuItem />

            <NaviusContextMenuGroup>
                <NaviusContextMenuItem />
            </NaviusContextMenuGroup>

            <NaviusContextMenuCheckboxItem>
                <NaviusContextMenuItemIndicator />
            </NaviusContextMenuCheckboxItem>

            <NaviusContextMenuRadioGroup>
                <NaviusContextMenuRadioItem>
                    <NaviusContextMenuItemIndicator />
                </NaviusContextMenuRadioItem>
            </NaviusContextMenuRadioGroup>

            <NaviusContextMenuSub>
                <NaviusContextMenuSubTrigger />
                <NaviusContextMenuSubContent />
            </NaviusContextMenuSub>

            <NaviusContextMenuSeparator />
            <NaviusContextMenuArrow />
        </NaviusContextMenuPopup>
    </NaviusContextMenuPositioner>
</NaviusContextMenu>

Root

Contains all the parts of a context menu. Owns open state. Renders no DOM.

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.
Dir	string?	-	Reading direction: "ltr" or "rtl". Cascaded to submenus; flips roving arrow keys.
ChildContent	RenderFragment?	-	The context menu’s parts.

Trigger

The area that opens the context menu. Wrap the target and right-click within its bounds. Renders a div.

Prop	Type	Default	Description
Disabled	bool	false	Disables opening the menu.
ChildContent	RenderFragment?	-	The right-clickable content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Popup

The menu surface that pops out when the context menu is open. Wrapped by the Positioner and self-portaled to the document body. Renders a div with role="menu". The Side / Align / SideOffset / AlignOffset / AvoidCollisions / CollisionPadding / Sticky / HideWhenDetached / ArrowPadding props are set on the enclosing NaviusContextMenuPositioner part (a real anatomy part not broken out into its own section here).

Prop	Type	Default	Description
Side	string	"right"	Preferred side (set on the Positioner). A context menu grows to the inline-end from the cursor point.
Align	string	"start"	Alignment along the side (set on the Positioner).
SideOffset	double	2	Distance in px from the anchor along the side (set on the Positioner).
AlignOffset	double	0	Offset in px along the alignment axis (set on the Positioner).
AvoidCollisions	bool	true	Avoid collisions with the viewport boundary (set on the Positioner).
CollisionPadding	double?	-	Padding in px between the popup and the collision boundary (set on the Positioner).
Sticky	string?	-	Sticky behavior while scrolling (set on the Positioner).
HideWhenDetached	bool	false	Hide the popup when the anchor is fully clipped/detached (set on the Positioner).
ArrowPadding	double	0	Padding in px between the arrow and the popup edges (set on the Positioner).
Loop	bool	false	When true, arrow navigation wraps at the ends.
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.
OnCloseAutoFocus	EventCallback<NaviusCloseAutoFocusEventArgs>	-	Fires when focus returns to the trigger area on close; cancelable.
ChildContent	RenderFragment?	-	The menu’s items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Item

The component that contains the context menu items. Renders a div with role="menuitem".

Prop	Type	Default	Description
Disabled	bool	false	Disables the item.
TextValue	string?	-	Overrides the type-ahead match text (for icon/complex content).
OnSelect	EventCallback<NaviusSelectEventArgs>	-	Cancelable. Fires when the item is chosen; PreventDefault() keeps the menu open.
ChildContent	RenderFragment?	-	Item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Group

Used to group multiple items. Renders a div with role="group".

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	The grouped items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Label

Used to render a label. Won’t be focusable using arrow keys. Renders a div.

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

CheckboxItem

An item that can be controlled and rendered like a checkbox. Renders a div with role="menuitemcheckbox".

Prop	Type	Default	Description
Checked	bool?	-	Controlled tri-state checked value (null = indeterminate). Pair with CheckedChanged (@bind-Checked).
CheckedChanged	EventCallback<bool?>	-	Fires when the controlled Checked value should change.
DefaultChecked	bool?	-	Initial checked value for uncontrolled use (null = indeterminate).
Disabled	bool	false	Disables the item.
TextValue	string?	-	Overrides the type-ahead match text.
OnSelect	EventCallback<NaviusSelectEventArgs>	-	Cancelable. PreventDefault() keeps the menu open after toggling.
ChildContent	RenderFragment?	-	Item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

RadioGroup

Used to group multiple radio items. Renders a div with role="group".

Prop	Type	Default	Description
Value	string?	-	Controlled selected value. Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string?>	-	Fires when the controlled Value should change.
DefaultValue	string?	-	Initial selected value for uncontrolled use.
ChildContent	RenderFragment?	-	The radio items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

RadioItem

An item that can be controlled and rendered like a radio. Renders a div with role="menuitemradio".

Prop	Type	Default	Description
Value	string	-	This item’s value within the radio group. Required.
Disabled	bool	false	Disables the item.
TextValue	string?	-	Overrides the type-ahead match text.
OnSelect	EventCallback<NaviusSelectEventArgs>	-	Cancelable. PreventDefault() keeps the menu open after selecting.
ChildContent	RenderFragment?	-	Item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

ItemIndicator

Renders when the parent CheckboxItem or RadioItem is checked. Style directly, or use as a wrapper for an icon. Renders a span.

Prop	Type	Default	Description
ForceMount	bool	false	Keeps the indicator mounted even when unchecked, for exit animations.
ChildContent	RenderFragment?	-	Indicator content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered span.

Separator

Used to visually separate items in the context menu. Renders a div with role="separator".

Prop	Type	Default	Description
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Arrow

An optional arrow element rendered alongside the content, to help visually link the cursor point with the content. Renders an svg.

Prop	Type	Default	Description
Width	double	10	Arrow width in px.
Height	double	5	Arrow height in px.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered svg.

Sub

Contains all the parts of a submenu. Owns its own open state. Renders no DOM.

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.
ChildContent	RenderFragment?	-	The SubTrigger and SubContent.

SubTrigger

An item that opens a submenu. Must be rendered inside a Sub. Renders a div with role="menuitem".

Prop	Type	Default	Description
Disabled	bool	false	Disables the sub-trigger.
TextValue	string?	-	Overrides the type-ahead match text.
Dir	string?	-	Reading direction; "rtl" swaps the open/close arrow keys. Falls back to the cascaded direction, then "ltr".
ChildContent	RenderFragment?	-	Sub-trigger content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

SubContent

The component that pops out when a submenu is open. Must be rendered inside a Sub. Renders a div with role="menu".

Prop	Type	Default	Description
Side	string	"right"	Submenus open to the side; "rtl" flips to "left".
Align	string	"start"	Alignment along the side.
SideOffset	double	0	Distance in px from the SubTrigger along the side.
AlignOffset	double	0	Offset in px along the alignment axis.
AvoidCollisions	bool	true	Avoid collisions with the viewport boundary.
CollisionPadding	double?	-	Padding in px between the submenu and the collision boundary.
Loop	bool	false	When true, arrow navigation wraps at the ends.
ForceMount	bool	false	Keeps the submenu mounted while closed, for exit animations.
Dir	string?	-	Reading direction; "rtl" flips the preferred side and the close key.
ChildContent	RenderFragment?	-	The submenu’s items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Data attributes

Part	Attribute	Description
Trigger	data-popup-open	Present while the menu is open.
Trigger	data-disabled	Present when disabled.
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	"left" | "right" | "top" | "bottom"
Popup	data-align	"start" | "center" | "end"
Item	data-highlighted	Present when highlighted.
Item	data-disabled	Present when disabled.
CheckboxItem	data-checked / data-unchecked	Present when checked / unchecked.
CheckboxItem	data-indeterminate	Present when in the indeterminate state.
CheckboxItem	data-highlighted	Present when highlighted.
CheckboxItem	data-disabled	Present when disabled.
RadioItem	data-checked / data-unchecked	Present when checked / unchecked.
RadioItem	data-highlighted	Present when highlighted.
RadioItem	data-disabled	Present when disabled.
ItemIndicator	data-checked / data-unchecked	Present when checked / unchecked.
ItemIndicator	data-indeterminate	Present when in the indeterminate state.
Separator	data-orientation	"horizontal"
SubTrigger	data-popup-open	Present while the submenu is open.
SubTrigger	data-highlighted	Present when highlighted.
SubTrigger	data-disabled	Present when disabled.
SubContent	data-open	Present while open.
SubContent	data-closed	Present while closing (through the exit transition).
SubContent	data-side	"left" | "right" | "top" | "bottom"
SubContent	data-align	"start" | "center" | "end"

Keyboard interactions

Key	Behavior
Space	Activates the focused item.
Enter	Activates the focused item.
ArrowDown	Moves focus to the next item.
ArrowUp	Moves focus to the previous item.
ArrowRight	When focus is on a SubTrigger, opens the submenu and moves focus to its first item.
ArrowLeft	When focus is inside a submenu, closes it and moves focus to the parent SubTrigger.
Home	Moves focus to the first item.
End	Moves focus to the last item.
Esc	Closes the context menu, returning focus to the trigger when the trigger is focusable.

ARIA mechanism

The Popup wires role="menu" with roving tabindex to manage focus movement among menu items, plus type-ahead support. Items wire role="menuitem", role="menuitemcheckbox", or role="menuitemradio" as appropriate, with aria-checked on the checkbox/radio variants. SubContent carries aria-labelledby pointing at its SubTrigger’s id, giving the submenu an accessible name. A Group wires aria-labelledby to a nested Label’s generated id, so screen readers announce the label as the group’s name. The Trigger renders a non-focusable element by default, so keyboard invocation (ContextMenu / Shift+F10) and focus return on Esc only apply when the trigger can receive focus (add tabindex="0" to enable it). This implements the WAI-ARIA APG menu pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.