Toggle Group

Overview

ToggleGroup is a set of two-state buttons sharing one pressed set. Multiple switches between a single pressed value (radio-like: pressing the active item clears it) and many. It can be controlled (@bind-Value) or uncontrolled (DefaultValue), and drives roving tabindex over its items so the group is a single Tab stop with arrow keys moving focus between items.

Anatomy

@using Navius.Primitives.Components.ToggleGroup

<NaviusToggleGroup>
    <NaviusToggleGroupItem />
</NaviusToggleGroup>

Root

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

Prop	Type	Default	Description
Multiple	bool	false	When true, multiple items can be pressed at once. Default is single (radio-like): pressing the active item clears it.
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 for uncontrolled use.
Disabled	bool	false	Disables every item in the group.
Orientation	string	"horizontal"	"horizontal" or "vertical"; drives the arrow-key axis.
RovingFocus	bool	true	When true, the group is a single Tab stop and arrows move a roving focus between items. When false, every enabled item is its own Tab stop and arrow navigation is disabled.
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". In RTL, horizontal arrow semantics swap.
ChildContent	RenderFragment?	-	The group’s items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Item

An individual two-state toggle button within the group. Renders a button.

Prop	Type	Default	Description
Value	string	""	This item’s value within the group’s pressed set.
Disabled	bool	false	Disables this item; skipped by roving focus.
ChildContent	RenderFragment?	-	Item content.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Root	data-orientation	"horizontal" | "vertical".
Root	data-multiple	Present when Multiple is enabled.
Root	data-disabled	Present when disabled.
Item	data-pressed	Present when the item is pressed (on).
Item	data-disabled	Present when disabled.

Keyboard interactions

Key	Behavior
Tab	Moves focus into and out of the group (a single Tab stop).
Space	Toggles the focused item on or off.
Enter	Toggles the focused item on or off.
ArrowDown	Moves focus to the next item (vertical orientation).
ArrowUp	Moves focus to the previous item (vertical orientation).
ArrowRight	Moves focus to the next item (horizontal orientation).
ArrowLeft	Moves focus to the previous item (horizontal orientation).
Home	Moves focus to the first item.
End	Moves focus to the last item.

ARIA mechanism

Uses roving tabindex to manage focus, implementing the roles and keyboard map of the toolbar WAI-ARIA APG pattern. The Root wires role="group". Each Item wires aria-pressed reflecting its on/off state; only the seated item carries tabindex="0", the rest tabindex="-1". This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.