Rating

Left unbound like the first one below, the BitRating keeps its own state with no binding or event handler involved, and DefaultValue only picks where that state starts. Disabling it greys the items out and takes it out of the interaction entirely. ReadOnly is the other half of that: the value is still shown at full contrast, but nothing about it can be changed - which is 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, while a disabled one is still a group, only an unavailable one. Notice the read-only one below carries a fractional value: partial fills are rendered whether or not the user could ever have picked them.

Max is both the highest value the rating accepts and the number of items it renders, so it is the scale of the whole control. Five is the familiar default, but a coarser three-point scale or a much finer one are just as valid; the items wrap when the row runs out of room, which is what keeps a 100-point rating usable inside a narrow container. A value above the Max is pulled back down to it, so the scale can be tightened at runtime without leaving an impossible value behind. And at the other extreme, a Max of 1 turns the rating into the compact single-star badge that sits next to a numeric score and a review count.

Vertical stacks the items into a column instead of a row, and fills it from the bottom up so that "more" is up - the same direction the ArrowUp key already means. Everything else follows: a fractional value fills its item from the bottom edge rather than the leading one, the transparent slices a fine Precision lays over an item are stacked the same way, and the group announces itself as vertically oriented so a screen reader describes the arrangement the user is actually facing. It is the shape to reach for when the rating sits beside a vertical bar chart or in a narrow column where a row of five stars would not fit.

Precision is the smallest change the user can make, expressed as a fraction of a single item. The default of 1 only allows whole items; 0.5 adds halves, 0.25 quarters, and 0.1 makes every tenth selectable. Below a whole item 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 exactly the same amount, which keeps the fractions reachable without a pointer. A precision that does not divide an item evenly is rounded to the closest number of equal steps, so the items always end on a whole value, and an item is never split into more than a hundred steps. Remember it constrains only what the user can pick: a value bound from elsewhere is always drawn at its exact precision.

A rating starts at the first item 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 to 1, so the rating can start empty - though the user still cannot get back to it. AllowClear is what adds that way back: clicking the item that is already selected, or pressing Delete or Backspace, returns the rating to 0. Since an unrated rating is the whole point of clearing, AllowClear opens up the 0 on its own, without AllowZeroStars.

By default a rating is cumulative: picking the fourth item fills the first four, because four stars means "four out of five". HighlightSelectedOnly switches that to a scale of standalone choices where only the item matching the value is filled - the right reading when the items are faces, moods or grades rather than a quantity that accumulates. 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 the rating restores what is actually bound. OnHoverChange reports that previewed value as it changes, and null once the pointer leaves - which is how the familiar word-per-star caption below is built. At a fractional Precision the preview follows the slices too, so the caption can react to a half step. NoHoverPreview turns the whole behaviour off for the rare case where the preview competes with something else on the page.

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. For icons from an external library, see the External Icons section below.

GetSelectedIcon and GetUnselectedIcon answer with the icon of a single position instead of one pair for the whole scale, which is what turns a rating into a scale that changes shape as it fills - thumbs down at the low end and thumbs up at the high end, or a different face at every step. Each callback receives the one-based position of the item and may return null to fall back to SelectedIcon / SelectedIconName, so only the positions that need their own glyph have to be answered. This is the lightweight half of ItemTemplate: the component keeps drawing the item, so the two-layer partial fill of a fractional value goes on working.

ItemTitles gives each item its own native tooltip, in order, so hovering an item spells out what it means instead of leaving the user to count stars. The same words double as the accessible name of the item, which is a better answer for a screen reader than "4 of 5" - unless AriaLabelFormat overrides it. A list shorter than the rating simply leaves the remaining items without a tooltip, and they fall back to their position in the scale.

ItemTemplate replaces the pair of icons of every item 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 describing the item - its Index, the Percentage it is filled by, whether it IsFull or merely IsSelected, and both the previewed DisplayValue and the committed Value - which is enough to drive anything from a numbered scale to the mood faces below. Note that a template renders whatever you give it 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 partial fill instead.

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 in both directions, which is why the number field and the stars below stay in step whichever one is used. Notice the number field can push a fractional value into a rating whose Precision is 1: the constraint is on what the user can pick, never on what can be displayed.

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 altogether: setting Cancel on the BitRatingChangeArgs keeps the current value, and since the callback is awaited it can take its time - long enough to ask the user a question. The args carry both the incoming Value and the OldValue being left behind, so the decision can depend on the direction of the change; the second rating below refuses to be lowered.

Inside an EditForm the BitRating is a form field like any other: it participates in the EditContext, reports its changes to it, and turns red while the value is invalid. Combined with AllowZeroStars, a Range annotation that starts at 1 is what turns "pick a rating" into a required question - the form starts unrated, and stays unsubmittable until something is picked. Required announces that expectation to assistive technologies ahead of the failure, rather than leaving the error message to be the first mention of it. The value itself travels in a hidden number input, so Name also makes the rating readable by a plain form post.

An interactive BitRating is a WAI-ARIA radiogroup of radio items and behaves like one: the whole row is a single tab stop that lands on the selected item, and from there the keyboard covers the entire scale. ArrowRight / ArrowUp raise the value by one Precision step and ArrowLeft / ArrowDown lower it; holding Shift - or using PageUp / PageDown, which need no modifier - moves a whole item at a time, so a rating split into tenths is still five presses wide rather than fifty. Home and End jump to the ends, the digit keys jump straight to that rating, and Delete or Backspace clear it where AllowClear permits. The horizontal arrows follow the reading direction, so they swap in RTL, and Escape is deliberately left alone so a rating inside a modal does not clear itself on the way to dismissing it.

Since a group of stars carries no visible label, name it: AriaLabel names the rating as a whole and AriaLabelFormat names each item, with {0} as the item and {1} as the max - "Select 3 of 5 stars". Without it an item is named by its tooltip from ItemTitles, and failing that by its position, so no item is ever left nameless. GetAriaLabel is a callback given the current value and the max, used as the name whenever AriaLabel is not set; a read-only rating, which is announced as a single image rather than a group of choices, falls back to a plain "3.5 of 5" if neither is provided. ValueTextFormat is what rewords that fallback - and the live announcement an interactive rating makes for a fractional value, which no single radio can express - for another language or for a scale whose items are not stars. 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 and lets the rest close the gap. The brackets below mark where each one sits.

The parameters of the rating 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 bands; the second derives its icons the same way, so a low score frowns and a high one smiles. This is the styling to reach for when "2 of 5" and "5 of 5" are different kinds of news rather than different amounts of the same one - and it needs no dedicated API, just callbacks and parameters that close over the bound value.

Color picks the theme color the filled part of the items is painted in, with Primary as the default. The unfilled part deliberately stays neutral whatever the color is, so it keeps reading as "not rated yet" instead of as a second, dimmer accent. The semantic colors - Success, Warning, Error and friends - 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. And since Color is an ordinary parameter, it can be computed from the bound value itself - which is what the Score-based styling section above builds on.

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 when both are set, 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 items, 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. A larger size also means larger hit areas, which matters most on touch and at fine precisions.

Style and Class reach the root element of the rating, which is enough for the framing around it. Styles and Classes go a level deeper and address the parts by name - Root, Button, IconContainer, SelectedIcon and UnselectedIcon - so the filled and unfilled halves can be styled apart from each other without leaving the component.

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 transparent slices of a fine Precision are laid out from that same edge, and the horizontal arrow keys swap so that ArrowLeft still means "more". The fractional read-only rating below shows the fill anchored on the correct side.