Toolbar

Overview

Toolbar is a container for grouping a set of controls, such as buttons, toggle groups, or links, behind a single roving-tabindex Tab stop. It composes buttons, links, separators, and toggle groups, supports horizontal and vertical orientation, and mirrors horizontal arrow keys under RTL.

Anatomy

@using Navius.Primitives.Components.Toolbar

<NaviusToolbar>
    <NaviusToolbarButton />
    <NaviusToolbarLink />

    <NaviusToolbarSeparator />

    <NaviusToolbarToggleGroup>
        <NaviusToolbarToggleItem />
    </NaviusToolbarToggleGroup>
</NaviusToolbar>

Root

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

Prop	Type	Default	Description
Orientation	string	"horizontal"	"horizontal" or "vertical". Drives the arrow-key axis.
Loop	bool	true	When true, arrow navigation wraps past the first/last item; when false it stops at the ends.
Dir	string?	-	Reading direction, "ltr" or "rtl". Under "rtl", horizontal arrow semantics swap. Falls back to the cascaded direction.
ChildContent	RenderFragment?	-	The toolbar’s items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div. Supply aria-label or aria-labelledby here.

Button

A focusable button control inside the toolbar. Renders a button.

Prop	Type	Default	Description
Disabled	bool	false	Disables this item and excludes it from the roving selector.
ChildContent	RenderFragment?	-	Button content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Link

A focusable link control inside the toolbar. Renders an a. Provide href via Attributes.

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

Separator

A non-focusable visual divider between groups of items. Renders a div with role="separator".

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

ToggleGroup

A set of toggle buttons inside the toolbar. Renders a div with role="group".

Prop	Type	Default	Description
Type	string	"single"	"single" (at most one pressed) or "multiple" (any number pressed).
Value	IReadOnlyList<string>?	-	Controlled pressed set. Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<IReadOnlyList<string>>	-	Fires when the controlled Value should change.
DefaultValue	IReadOnlyList<string>?	-	Initial pressed set when used uncontrolled.
Disabled	bool	false	Disables every item in the group.
ChildContent	RenderFragment?	-	The toggle items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

ToggleItem

A single toggle button inside a ToggleGroup. Renders a button with aria-pressed.

Prop	Type	Default	Description
Value	string	""	This item’s value.
Disabled	bool	false	Disables this item. Group-level Disabled also applies to every item.
ChildContent	RenderFragment?	-	Toggle item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Root	data-orientation	"horizontal" | "vertical".
Button	data-orientation	"horizontal" | "vertical".
Button	data-disabled	Present when disabled.
Link	data-orientation	"horizontal" | "vertical".
Separator	data-orientation	"horizontal" | "vertical" (perpendicular to the toolbar).
ToggleGroup	data-orientation	"horizontal" | "vertical".
ToggleGroup	data-disabled	Present when the group is disabled.
ToggleItem	data-pressed	Present when the item is pressed (on).
ToggleItem	data-orientation	"horizontal" | "vertical".
ToggleItem	data-disabled	Present when disabled.

Keyboard interactions

Key	Behavior
Tab	Moves focus into the toolbar, landing on the first enabled item. From inside, moves focus out of the toolbar.
ArrowRight	In horizontal orientation, moves focus to the next item.
ArrowLeft	In horizontal orientation, moves focus to the previous item.
ArrowDown	In vertical orientation, moves focus to the next item.
ArrowUp	In vertical orientation, moves focus to the previous item.
Home	Moves focus to the first item.
End	Moves focus to the last item.
Enter	Activates the focused item (toggles a ToggleItem, follows a Link).
Space	Activates the focused item (toggles a ToggleItem).

ARIA mechanism

Root renders role="toolbar" with aria-orientation. Only the first enabled item (a Button, Link, or ToggleItem) carries tabindex="0"; every other item carries tabindex="-1", and the engine moves DOM focus between them on the arrow keys plus Home/End, so the toolbar is a single Tab stop. Separator renders role="separator" with aria-orientation perpendicular to the toolbar’s axis and is excluded from the roving order. ToggleItem renders aria-pressed. Consumers supply aria-label or aria-labelledby on the Root. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.