Rating

Left unbound, the rating keeps its own state and DefaultValue only picks where that state starts. Disabling it greys the items out; ReadOnly keeps them at full contrast but frozen - the mode a rating spends most of its life in, summarizing what other people already rated. The difference runs deeper than the styling: a read-only rating stops being a group of choices and is announced as a single labelled image. Note its fractional value - partial fills are rendered whether or not the user could ever have picked them.

Label names the rating - and since a row of stars carries no text of its own, it is also what names it for a screen reader. Required marks it with an asterisk, LabelPlacement moves it beside the items for a compact row, and LabelTemplate replaces it with markup of your own, below a caption that spells the value out in words. Description is the hint under the items, pointed at by aria-describedby so it is announced after the name rather than as part of it, and DescriptionTemplate replaces it with markup while keeping that role. ItemTitles gives each item its own tooltip, in order, and those words double as the accessible name of the item; items past the end of the list fall back to their position.

Max is both the highest value the rating accepts and the number of items it renders. Five is the familiar default; the items wrap when the row runs out of room, which is what keeps a 100-point rating usable inside a narrow container, and a value above the Max is pulled back down to it so the scale can be tightened at runtime. A Max of 1 turns the rating into the compact single-star badge beside a numeric score.

Vertical stacks the items into a column and fills it from the bottom up, so that "more" is up - the direction ArrowUp already means. A fractional value fills its item from the bottom edge, the slices of a fine Precision are stacked the same way, and the group announces itself as vertically oriented.

Precision is the smallest change the user can make, as a fraction of a single item: 1 allows whole items only, 0.5 adds halves, 0.1 makes every tenth selectable. Each item is covered by that many transparent slices, so the half a pointer lands on is the half that gets committed, and the arrow keys step by the same amount. A precision that does not divide an item evenly is rounded to the closest number of equal steps, and an item is never split into more than a hundred. It constrains what the user can pick, never what can be shown: a value bound from elsewhere is always drawn at its exact precision. It also sets the floor of the scale - the smallest rating that can still be given is one step, so a half-star rating reaches 0.5 without having to open up the unrated 0 that AllowZeroStars is for.

A rating starts at its smallest step - a whole item at the default Precision - unless it is told that "not rated" is a legitimate answer. AllowZeroStars says exactly that: a value of 0 is kept instead of being pulled up, so the rating can start empty. That makes 0 part of the scale rather than an action, so the keys that reach the ends of the range - Home and 0 - reach it while the pointer, which always commits at least one step, cannot.

AllowClear is clearing as an action: clicking the item that is already selected, or pressing Delete or Backspace, returns the rating to 0 - which is why it opens up the 0 on its own. Because the preview is always the value a click would commit, the items empty while the pointer rests on the committed value, so clearing is discovered rather than explained.

By default a rating is cumulative: picking the fourth item fills the first four, because four stars means "four out of five". HighlightSelectedOnly switches to a scale of standalone choices where only the matching item is filled - the right reading when the items are faces, moods or grades rather than a quantity. A fractional value still fills its own item by the fraction it covers, so the mode composes with Precision instead of rounding against it.

While the pointer is over the items the rating previews the value a click would commit, painting it in the hover shade so it reads as a proposal rather than as the committed value; leaving restores what is bound. OnHoverChange reports that previewed value as it changes, and null once the pointer leaves - which is all a caption needs to follow the pointer, down to a half step at a fractional Precision. NoHoverPreview turns off the preview the component paints, for a page that competes with it or draws one of its own - the items still grow under the pointer and dip under a press, since those are affordances and not values, and OnHoverChange goes on reporting. The press is what carries a touch device, which has no hover to preview with at all.

SelectedIconName and UnselectedIconName replace the pair of built-in star glyphs, which is what lets the same component read as a like, a heart or a checklist. The two icons are drawn on top of each other and the selected one is clipped to the fill percentage, so the pair works best when both glyphs share an outline - a hollow shape and its filled twin.

GetSelectedIcon and GetUnselectedIcon answer for a single position instead of the whole scale, which turns a rating into one that changes shape as it fills. Each receives the one-based position and may return null to fall back to the pair above, so only the positions that need their own glyph have to be answered - and since the component keeps drawing the item, the two-layer partial fill of a fractional value goes on working. For icons from an external library see External Icons.

ItemTemplate replaces the pair of icons with content of your own while the BitRating keeps everything around it: the hit areas, the hover preview, the keyboard handling and the accessibility. The template receives a BitRatingItemContext - the item's Index, the Percentage it is filled by, whether it IsFull or merely IsSelected, whether it IsCurrent (the one the shown value lands in, which the numbered scale below rings), and both the previewed DisplayValue and the committed Value. A template renders as a whole, so a partial fill is yours to express if it matters; when all you need is a different glyph per position, GetSelectedIcon keeps the built-in one. The drawing is hidden from assistive technologies just as the built-in glyphs are, so the numbers and faces below are not appended to the names the items already carry.

A one-way Value makes the rating a pure display of whatever the page decides - the toggle below drives it and clicking the stars does nothing, because there is nowhere for the new value to go. @bind-Value completes the circuit both ways. Notice the number field can push a fractional value into a rating whose Precision is 1.

OnChange fires after a new value lands, which is what an uncontrolled rating reports its result through. OnChanging runs first and can stop the change: setting Cancel on the BitRatingChangeArgs keeps the current value, and since the callback is awaited it can take long enough to ask the user a question. The args carry both the incoming Value and the OldValue, so the decision can depend on the direction of the change - the second rating below refuses to be lowered. OnFocusIn and OnFocusOut report the focus arriving at and leaving the rating as a whole rather than each item, so moving along the scale with the arrow keys does not read as leaving and re-entering it.

Inside an EditForm the rating is a form field like any other: it joins the EditContext, reports its changes to it, and turns red while the value is invalid. Combined with AllowZeroStars, a Range annotation starting at 1 turns "pick a rating" into a required question - the form starts unrated and stays unsubmittable. Required announces that expectation ahead of the failure and marks the label with an asterisk. The value travels in a hidden number input, so Name also makes the rating readable by a plain form post.

aria-invalid says that something is wrong but not what, so the failure message is given an id and pointed at from the rating. A splatted aria-describedby is carried over rather than replaced - both it and the component's own Description are kept, since the attribute is a list - so the reason is announced with the field instead of only being visible under it.

An interactive rating is a WAI-ARIA radiogroup of radio items: the whole row is a single tab stop landing on the selected item, and from there the keyboard covers the scale, stepping by the Precision.

The horizontal arrows follow the reading direction and swap in RTL. A held Ctrl, Alt or Meta hands the key back to the page, so Alt+← still goes back, and Escape is left alone so a rating inside a modal does not clear itself on the way to dismissing it. Every item is a pointer target of at least 24×24 CSS pixels whatever the Size, and the fill survives a forced-colors palette, where it is re-established in system colors rather than left to color alone.

Name the group: a visible Label does it, and AriaLabel or AriaLabelledBy where the name is already written elsewhere on the page. AriaLabelFormat names each item, with {0} as the item and {1} as the max - "Select 3 of 5 stars"; without it an item falls back to its ItemTitles tooltip and then to its position, so no item is ever nameless. GetAriaLabel builds the group's name from the current value and the max. ValueTextFormat rewords what is announced for a value no radio can carry - a fractional one, and the value a read-only rating adds to its own name. AutoFocus hands the rating the focus as the page renders.

Visibility decides how the rating disappears: Hidden keeps its box and only stops painting it, so the layout around it does not move, while Collapsed removes the box entirely. The brackets below mark where each one sits.

The parameters are re-read on every render, so they can be computed from the very value the rating is bound to - which is all it takes to restyle the scale by the score it shows. The first rating below derives its Color from its own value, turning from red through orange to green as the score climbs; the second derives its icons the same way, so a low score frowns and a high one smiles. No dedicated API is involved.

BitParams carries a BitRatingParams down to every rating under it, so a review list, a card or a whole page sets the shared scale, glyphs and mode once instead of on every rating. What it carries is a default and not an override: a rating that writes a parameter for itself keeps its own value, and only what it left unset is filled in from the cascade - parameter by parameter, which is how the last rating below steps out of the group it is in without the group knowing about it.

Color picks the theme color the filled part of the items is painted in, with Primary as the default; the hover shade, the press shade and the focus ring all come from the same role. The unfilled part stays neutral whatever the color is, so it keeps reading as "not rated yet" instead of as a second, dimmer accent. The semantic colors tie the rating to what the score means, while the Background, Foreground and Border families keep it legible on non-default surfaces like the inverted panel below.

SelectedIcon and UnselectedIcon take a BitIconInfo instead of a built-in icon name, which is how icons from an external library are used. BitIconInfo.Fa and BitIconInfo.Bi build the class names for FontAwesome and Bootstrap Icons, BitIconInfo.Css takes whatever classes you hand it, and a plain string works too. They take precedence over SelectedIconName / UnselectedIconName, and the same type is what the per-item GetSelectedIcon callback returns. Remember to reference the stylesheet of the icon library itself.

Size scales the whole control - the glyphs, the label and the description - from the Small that fits inline next to a line of text to the Large that carries a rating asked as the main question on a page. Medium is the default. The pointer target of an item never drops below 24×24 CSS pixels, so a smaller size buys a smaller glyph rather than a harder one to hit.

Style and Class land on the root. Styles and Classes reach the parts by name - Root, LabelContainer, Label, Description, Container, Button, IconContainer, SelectedIcon and UnselectedIcon - so the filled and unfilled halves can be styled apart from each other. Prefer Classes where your CSS should own states such as hover and focus, which inline styles cannot express. Each item also carries data-is-current, which marks the one the shown value lands in - the fourth of a 3.5, and the one under the pointer while a preview is running - so the item being picked can be told apart from the run of filled ones behind it.

The rating also reads a set of CSS variables off its root for what no parameter covers. They inherit, so a value on :root or any ancestor re-skins every rating below it, and one on the Style of an instance re-skins that one alone.

Set once on an ancestor, inherited by every rating inside it:

Setting Dir to Rtl mirrors the whole rating: the first item moves to the right, the partial fill of a fractional value grows from the right edge of its item, the slices of a fine Precision are laid out from that same edge, and the horizontal arrow keys swap so that ArrowLeft still means "more".