Rating

Overview

Rating renders a role="radiogroup" of role="radio" stars with roving tabindex; the value logic lives on the root, so arrow keys move focus and value together. It can be controlled (@bind-Value, a decimal?) or uncontrolled (DefaultValue), and a hidden input mirrors the value into form submission when Name is set.

Anatomy

@using Navius.Primitives.Components.Rating

@* Auto-rendered stars: *@
<NaviusRating @bind-Value="_rating" Max="5" />

@* Or your own item children: *@
<NaviusRating @bind-Value="_rating">
    <NaviusRatingItem>@* star glyph *@</NaviusRatingItem>
</NaviusRating>

Root

Owns the value, the keyboard model, and the hover preview. Renders a div with role="radiogroup". Auto-renders Max Item children when given no ChildContent.

Prop	Type	Default	Description
Value	decimal?	-	Controlled value (null = unrated). Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<decimal?>	-	Fires when the controlled Value should change.
DefaultValue	decimal?	-	Initial value when used uncontrolled.
Max	int	5	Number of visual stars.
AllowHalf	bool	false	Enables half-star values via pointer half-zones and 0.5 keyboard steps.
AllowClear	bool	true	Re-selecting the current value (or arrowing below 1) clears to unrated.
ReadOnly	bool	false	Focusable but non-editable.
Disabled	bool	false	Disables the whole group.
Required	bool	false	Marks the bubble input required for native form validation.
Invalid	bool	false	Marks the group invalid (aria-invalid).
Name	string?	-	Form field name; when set, renders a hidden bubble input for native submission.
Label	Func<decimal, string>?	-	Accessible-name factory for a star value; defaults to “N star(s)”.
Dir	string?	-	Reading direction. Under "rtl" the horizontal arrows are mirrored.
ChildContent	RenderFragment?	-	Explicit Item children. When omitted, Max items render automatically.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered div.

Item

One star; its index is assigned by registration order. Renders a button with role="radio" (plus two aria-hidden half-zones under AllowHalf).

Prop	Type	Default	Description
ChildContent	RenderFragment?	-	The star glyph.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered button.

Data attributes

Part	Attribute	Description
Root	data-disabled	Present when disabled.
Root	data-readonly	Present when read-only.
Item	data-state	"full" | "half" | "empty", from the hover preview or the committed value.
Item	data-index	The 1-based star index.
Item	data-value	The whole value this star selects.
Item	data-checked / data-unchecked	Whether this star holds the value.
Item	data-highlighted	Present while covered by a hover preview.
Item	data-readonly / data-disabled	Mirrors the group state.

Keyboard interactions

Key	Behavior
Arrow Up / Arrow Right	Raises the rating by one step (0.5 with AllowHalf; mirrored under RTL).
Arrow Down / Arrow Left	Lowers the rating by one step, clearing below 1 when AllowClear.
Home / End	Sets the rating to 1 / Max.
1-9	Jumps directly to that whole-star rating (capped at Max).
Backspace / Delete	Clears to unrated when AllowClear.
Space / Enter	Activates the focused star.

ARIA mechanism

The Root wires role="radiogroup" with roving tabindex: only the checked star (or the first when unrated) is in the Tab order. Each Item is role="radio" with aria-checked; the star holding a fractional value announces the real value (a 3.5 reads “3.5 stars”). The group is labelled “Rating” unless the consumer supplies an aria-label / aria-labelledby. This implements the WAI-ARIA APG radio group pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.