Menubar

Overview

Menubar is a horizontal row of menus with at most one open at a time. It can be controlled (@bind-Value) or uncontrolled (DefaultValue), and drives roving tabindex across the top-level triggers with “follow focus” reopening as arrow keys move between them. Menus support submenus, checkbox items and radio groups, and each menu’s Popup self-portals to document.body, anchored to its trigger.

Anatomy

@using Navius.Primitives.Components.Menubar

<NaviusMenubar>
    <NaviusMenubarMenu>
        <NaviusMenubarTrigger />
        <NaviusMenubarPortal>
            <NaviusMenubarPositioner>
                <NaviusMenubarPopup>
                    <NaviusMenubarArrow />
                    <NaviusMenubarItem />
                    <NaviusMenubarGroup>
                        <NaviusMenubarLabel />
                        <NaviusMenubarItem />
                    </NaviusMenubarGroup>
                    <NaviusMenubarCheckboxItem>
                        <NaviusMenubarItemIndicator />
                    </NaviusMenubarCheckboxItem>
                    <NaviusMenubarRadioGroup>
                        <NaviusMenubarRadioItem>
                            <NaviusMenubarItemIndicator />
                        </NaviusMenubarRadioItem>
                    </NaviusMenubarRadioGroup>
                    <NaviusMenubarSeparator />
                    <NaviusMenubarSub>
                        <NaviusMenubarSubTrigger />
                        <NaviusMenubarSubContent />
                    </NaviusMenubarSub>
                </NaviusMenubarPopup>
            </NaviusMenubarPositioner>
        </NaviusMenubarPortal>
    </NaviusMenubarMenu>
</NaviusMenubar>

Root

Contains all the parts of a menubar. Renders a div with role="menubar".

Prop	Type	Default	Description
`Value`	`string?`	-	Controlled open menu value (the open menu’s `Value`, or null). Pair with `ValueChanged` (`@bind-Value`).
`ValueChanged`	`EventCallback<string?>`	-	Fires when the controlled `Value` should change.
`DefaultValue`	`string?`	-	Initial open menu value for uncontrolled use.
`Orientation`	`string`	`"horizontal"`	`"horizontal"` or `"vertical"`.
`Dir`	`string?`	-	Reading direction, `"ltr"` or `"rtl"`. Flips trigger roving and submenu open/close.
`Loop`	`bool`	`false`	Keyboard focus loops from the last trigger back to the first, and vice versa.
`Modal`	`bool`	`true`	When modal, the open menu locks page scroll and blocks outside pointer interaction.
`ChildContent`	`RenderFragment?`	-	The menubar’s menus.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Groups a trigger and its content into one menu, identified by Value. Renders no DOM of its own.

Prop	Type	Default	Description
`Value`	`string`	- (required)	Identity of this menu within the menubar. Must be unique.
`ChildContent`	`RenderFragment?`	-	The menu’s trigger and content.

Trigger

Toggles the menu it belongs to. Renders a button with role="menuitem".

Prop	Type	Default	Description
`Disabled`	`bool`	`false`	Disables the trigger; skipped by roving focus.
`ChildContent`	`RenderFragment?`	-	Trigger label content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Portal

Teleports the popup into document.body (or Container). Renders no DOM of its own.

Prop	Type	Default	Description
`Container`	`string?`	`document.body`	CSS selector for the mount target.
`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). A flag-setter; the Popup renders the positioning element the engine anchors and writes data-side / data-align onto.

Prop	Type	Default	Description
`Side`	`string`	`"bottom"`	Preferred side: `top`, `right`, `bottom`, `left`.
`Align`	`string`	`"start"`	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` or `always`.
`HideWhenDetached`	`bool`	`false`	Hide the popup (`data-anchor-hidden`) when the anchor is fully clipped/detached.
`ArrowPadding`	`double`	`0`	Padding in px between the arrow and the popup edges.
`ChildContent`	`RenderFragment?`	-	The Popup.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the positioning element.

The menu surface, wrapped by the Positioner. Self-portals; renders a div with role="menu". Manages roving focus over its items rather than a focus trap.

Prop	Type	Default	Description
`Loop`	`bool`	`false`	When true, arrow navigation among items wraps at the ends.
`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 menu’s items.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Arrow

An optional arrow pointing from the Popup at its Trigger. 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`.

Item

A selectable item inside a menu. Renders a div with role="menuitem".

Prop	Type	Default	Description
`Disabled`	`bool`	`false`	Disables the item; skipped by roving focus and doesn’t activate.
`TextValue`	`string?`	-	Overrides the type-ahead match string. Defaults to the item’s text content.
`OnSelect`	`EventCallback<NaviusSelectEventArgs>`	-	Invoked when chosen. Call `PreventDefault` to keep the menu open after selection.
`ChildContent`	`RenderFragment?`	-	Item content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Group

Groups related items. Renders a div with role="group".

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

Label

A non-interactive label, skipped by roving focus. 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 checked, like a checkbox. Renders a div with role="menuitemcheckbox".

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

RadioGroup

Groups radio items so exactly one is selected. 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 group’s radio items.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

RadioItem

An item that can be checked within a radio group. Renders a div with role="menuitemradio".

Prop	Type	Default	Description
`Value`	`string`	- (required)	This item’s value within the radio group. Must be unique.
`Disabled`	`bool`	`false`	Disables the item.
`TextValue`	`string?`	-	Overrides the type-ahead match string.
`OnSelect`	`EventCallback<NaviusSelectEventArgs>`	-	Invoked when chosen. Call `PreventDefault` to keep the menu open after selection.
`ChildContent`	`RenderFragment?`	-	Item content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

ItemIndicator

Renders only when its parent checkbox/radio item is checked. Renders a span.

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

Separator

A visual divider between items. Renders a div with role="separator".

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

Sub

Contains the parts of a submenu, with its own open state. 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.
`ChildContent`	`RenderFragment?`	-	The submenu’s trigger and content.

SubTrigger

An item that opens a submenu. Renders a div with role="menuitem".

Prop	Type	Default	Description
`Disabled`	`bool`	`false`	Disables the trigger; skipped by roving focus, never opens.
`TextValue`	`string?`	-	Overrides the type-ahead match string.
`Dir`	`string?`	-	Reading direction; flips the open arrow key. Falls back to the cascaded direction, then `"ltr"`.
`ChildContent`	`RenderFragment?`	-	Trigger content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

SubContent

The submenu surface, anchored to the SubTrigger and portaled. Renders a div with role="menu".

Prop	Type	Default	Description
`Side`	`string`	`"right"`	Preferred side; flips to `left` in `rtl`.
`Align`	`string`	`"start"`	Alignment along the side.
`SideOffset`	`double`	`0`	Distance in px from the anchor 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 popup and the collision boundary.
`Loop`	`bool`	`false`	When true, arrow navigation among items wraps at the ends.
`ForceMount`	`bool`	`false`	Keeps the submenu mounted while closed, for exit animations.
`Container`	`string?`	`document.body`	CSS selector for the mount target.
`Dir`	`string?`	-	Reading direction; falls back to the cascaded direction, then `"ltr"`.
`ChildContent`	`RenderFragment?`	-	The submenu’s items.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Data attributes

Part	Attribute	Description
Root	`data-orientation`	`"horizontal"` \| `"vertical"`.
Trigger	`data-popup-open`	Present while the menu is open.
Trigger	`data-highlighted`	Present when highlighted by roving focus.
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`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`.
Popup	`data-align`	`"start"` \| `"center"` \| `"end"`.
Popup	`data-orientation`	`"vertical"`.
Popup	`data-anchor-hidden`	Present when `HideWhenDetached` is set and the anchor is fully clipped/detached.
Item, CheckboxItem, RadioItem, SubTrigger	`data-highlighted`	Present when highlighted by roving focus.
Item, CheckboxItem, RadioItem, SubTrigger	`data-disabled`	Present when disabled.
CheckboxItem, RadioItem, ItemIndicator	`data-checked`	Present when checked.
CheckboxItem, RadioItem, ItemIndicator	`data-unchecked`	Present when unchecked.
CheckboxItem	`data-indeterminate`	Present when in the indeterminate state.
SubTrigger	`data-popup-open`	Present while the submenu is open.
SubContent	`data-open`	Present while open.
SubContent	`data-closed`	Present while closing (through the exit transition).
SubContent	`data-side`	`"top"` \| `"right"` \| `"bottom"` \| `"left"`.
SubContent	`data-align`	`"start"` \| `"center"` \| `"end"`.
SubContent	`data-orientation`	`"vertical"`.

Keyboard interactions

Key	Behavior
`Space`	When focus is on a trigger, opens the menu. When on an item, activates it.
`Enter`	When focus is on a trigger, opens the menu. When on an item, activates it.
`ArrowDown`	When focus is on a trigger, opens the menu and moves focus to the first item. When on an item, moves to the next item.
`ArrowUp`	When focus is on a trigger, opens the menu and moves focus to the last item. When on an item, moves to the previous item.
`ArrowRight`	When focus is on a trigger, moves to the next trigger. Inside an open menu, opens a submenu or moves to the next top-level menu (flipped in RTL).
`ArrowLeft`	When focus is on a trigger, moves to the previous trigger. Inside a submenu, closes it and returns focus to the SubTrigger; otherwise moves to the previous top-level menu (flipped in RTL).
`Home`	Moves focus to the first trigger or, inside a menu, the first item.
`End`	Moves focus to the last trigger or, inside a menu, the last item.
`Esc`	Closes the open menu and returns focus to its trigger.
`A`-`Z`, `a`-`z`	Type-ahead: moves focus to the next item whose label starts with the typed characters.

ARIA mechanism

Implements the roles, states and keyboard map of the menu and menubar WAI-ARIA APG pattern: the Root wires role="menubar"; each Trigger wires role="menuitem" with aria-haspopup="menu" and aria-expanded; each Popup wires role="menu" with aria-labelledby pointing at its trigger. Items wire role="menuitem", role="menuitemcheckbox", or role="menuitemradio" with aria-checked as appropriate. Roving tabindex governs both the top-level triggers and the items inside an open menu, so only one element in each is in the Tab order at a time. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.