Radio Group

Overview

RadioGroup is a set of checkable buttons where no more than one can be checked at a time. It uses roving tabindex so only the checked radio (or the first enabled one, if none is checked) sits in the Tab order; arrow keys move focus and selection together. It can be controlled (@bind-Value) or uncontrolled (DefaultValue), and renders a hidden mirror input per item so it participates in native form submission and validation.

Anatomy

@using Navius.Primitives.Components.RadioGroup

<NaviusRadioGroup>
    <NaviusRadioGroupItem>
        <NaviusRadioGroupIndicator />
    </NaviusRadioGroupItem>
</NaviusRadioGroup>

Root

Contains all the radio items. Renders a div with role="radiogroup".

Prop	Type	Default	Description
Value	string?	-	Controlled checked value. Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string?>	-	Fires when the controlled Value should change.
DefaultValue	string?	-	Initial checked value when used uncontrolled.
Disabled	bool	false	Disables every item in the group.
Required	bool	false	Marks every item required for native form validation.
Name	string?	-	Form field name applied to each item’s hidden mirror input.
Orientation	string?	-	"horizontal" or "vertical". Unset omits aria-orientation/data-orientation rather than defaulting.
Loop	bool	true	When true, arrow navigation wraps around the ends.
Dir	string?	-	Reading direction. Under "rtl" the horizontal arrows are mirrored. Falls back to the cascaded direction.
ChildContent	RenderFragment?	-	The radio items.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Item

An item in the group that can be checked. Renders a button with role="radio".

Prop	Type	Default	Description
Value	string	""	This item’s value.
Disabled	bool	false	Disables this item.
Required	bool	false	Marks this item required. Group-level Required also applies to every item.
ReadOnly	bool	false	Keeps this item focusable but its selection cannot be changed.
ChildContent	RenderFragment?	-	The Indicator.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Indicator

Renders when its item is checked. Renders a span. Style it as the radio dot.

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

Data attributes

Part	Attribute	Description
Root	data-orientation	"horizontal" | "vertical" (only when set).
Root	data-disabled	Present when disabled.
Item	data-checked	Present when checked.
Item	data-unchecked	Present when unchecked.
Item	data-disabled	Present when disabled.
Item	data-readonly	Present when read-only.
Item	data-required	Present when required.
Indicator	data-checked	Present when checked.
Indicator	data-unchecked	Present when unchecked.
Indicator	data-disabled	Present when disabled.
Indicator	data-readonly	Present when read-only.
Indicator	data-required	Present when required.

Keyboard interactions

Key	Behavior
Tab	Moves focus to the checked radio item, or the first enabled item when none is checked.
Space	Checks the focused radio item if it is not already checked.
ArrowDown	Moves focus and checks the next enabled radio item.
ArrowRight	Moves focus and checks the next enabled radio item (mirrored under rtl).
ArrowUp	Moves focus and checks the previous enabled radio item.
ArrowLeft	Moves focus and checks the previous enabled radio item (mirrored under rtl).
Home	Moves focus and checks the first enabled radio item.
End	Moves focus and checks the last enabled radio item.

ARIA mechanism

Root renders role="radiogroup" with aria-orientation (when Orientation is set) and aria-required. Each Item renders role="radio" with aria-checked, aria-readonly, and aria-required, and uses roving tabindex so only one item is Tab-reachable at a time. Arrow keys, Home, and End move focus and selection together between enabled items. This mechanism is covered by the Playwright browser test suite and gated by axe-core in CI.