Skip to content
Razor catalogue

On this page

@addTagHelper *, Webority.Ui.Razor

As an input

Use the input for a rating the reader gives, with hover to preview and a click or arrow keys to choose.

With helper text
How was the support?
Choose 1 to 5 stars.
Show code
<app-rating label="How was the support?" name="support" helper-text="Choose 1 to 5 stars."></app-rating>
Required, with an error
Quality
Choose a rating.
Show code
<app-rating label="Quality" name="quality" required="true" error="Choose a rating."></app-rating>

As a display

Use the display in a list row or on a card, read only; half draws the nearest half star.

Whole, half and with the number
The stars are hidden from assistive technology; the display has one name, "Quality: 4.3 out of 5".
Show code
<app-rating read-only="true" value="4" label="Quality"></app-rating>
<app-rating read-only="true" value="4.3" half="true" show-value="true" label="Quality"></app-rating>

Every option

Every value of every prop, one cell each.

value: the controlled rating

value="3": the rating the page holds
Quality

defaultValue: the starting rating

defaultValue: React only, Razor sets value="3"
Quality

onChange: the callback

onChange: React only, Razor posts the chosen rating with its form
Quality

max: how many stars

max="5" (default)
Quality
max="10"
Quality

read-only: a display, not an input

read-only="false" (default)
Quality
read-only: a display that says its number

half: the nearest half star, display only

half="false" (default): 4.3 draws four whole stars
half: 4.3 draws four and a half stars

show-value: the number beside the stars, display only

show-value="false" (default)
show-value: prints 4.3 beside the stars

size: the star size

size="md" (default)
Quality
size="sm"
Quality
size="lg"
Quality

label: the visible group label

label="Delivery speed": the visible label and the group name
Delivery speed

name: the form field name

name="rating-name": the form field name, no visible change
Quality

required: the required mark

required="false" (default)
Quality
required: the required mark, and aria-required on the group
Quality

disabled: no input

disabled="false" (default)
Quality
disabled: every star is disabled
Quality

error: the message below the stars

error="Choose a rating.": replaces the helper text
Quality
Choose a rating.

helper-text: the text below the stars

helper-text="Choose 1 to 5 stars.": the helper text
Quality
Choose 1 to 5 stars.

id: the control's id

id="every-option-rating": the id of the control, no visible change
Quality

input-class: a class on the stars

input-class: a class on the stars, for a product's own styling
Quality

class: a class on the field wrapper

class: a class on the field wrapper, for a product's own styling
Quality

loading: the busy state

loading="false" (default)
Quality
loading: a busy state that blocks input while data loads
Quality

help: the info-tip beside the label

help="Ratings are shown to other readers.": the info-tip content
Quality

help-label: the info-tip button's name

help-label: the accessible name of the info-tip button, shown with help
Quality

rating-label: the spoken group text

rating-label="Evaluation": spoken text only, no visible change
Quality

star-label: the spoken text for one star

star-label="{count} point": spoken text only, no visible change
Quality

stars-label: the spoken text for several stars

stars-label="{count} points": spoken text only, no visible change
Quality

value-text: the spoken text for the value

value-text="{value} of {max} points": spoken text only, no visible change
Quality

Guidance

What to do, and what to avoid.

Use it when

  • Feedback, review and satisfaction forms.
  • Showing an average or a given rating in a list or on a card.

Reach for something else when

  • A choice between named options. → AppRadioGroup
  • A numeric amount. → AppSlider

Reference

Try every prop, read the full list, and check keyboard and screen reader behaviour.

md sm lg
Quality
React, generated from the controls
<AppRating defaultValue={3} label="Quality" name="pg-rating" />
Razor, the same props
<app-rating label="Quality" value="3" name="pg-rating"></app-rating>

22 props. The 5 most used come first.

Used on most screens 5 props

PropTypeDefaultDescription
valuedefault - double - The rating (controlled as an input). A display may hold a fraction such as 4.3; an input rounds to a whole star.
maxdefault 5 int 5 How many stars.
halfdefault false bool false Display only: draw the value to the nearest half star.
show-valuedefault false bool false Display only: print the number beside the stars.
labeldefault - string - Input: the visible label and the group's name. Display: prefix of the spoken text.

Less common 17 props

PropTypeDefaultDescription
read-onlydefault false bool false A display, not an input.
sizedefault md sm | md | lg md The star size: 16, 20 or 28 pixels.
namedefault - string - Input only: the form field name. Defaults to a generated one.
rating-labeldefault Rating string Rating Replaces the built-in English text, for other languages.
star-labeldefault {count} star string {count} star Replaces the built-in English text, for other languages. Token: {count}.
stars-labeldefault {count} stars string {count} stars Replaces the built-in English text, for other languages. Token: {count}.
value-textdefault {value} out of {max} string {value} out of {max} Replaces the built-in English text, for other languages. Tokens: {value}, {max}.
requireddefault false bool false Input only: shows the required mark beside the label, and sets aria-required on the group and required on each star's input.
disableddefault false bool false Input only: disables every star's input and sets the disabled attribute on the control.
errordefault - string - Input only: message below the stars. Replaces the helper text.
helper-textdefault - string - Input only: helper text below the stars.
iddefault - string - The rating control's id; generated when left out.
input-classdefault - string - Input: extra class on the stars; class goes on the field wrapper.
classdefault - string - Classes on the field wrapper.
loadingdefault false bool false Shows a busy state and blocks input while data loads.
helpdefault - string - Input: info-tip content shown beside the label.
help-labeldefault More information string More information The accessible name of the info-tip button.

Screen reader

3 notes
  • The input is a radiogroup named by its label, and each star is a labelled radio (for example, 3 stars).
  • A read-only display has role img and speaks its value, for example 4.5 out of 5.
  • The stars are hidden from assistive technology in the display, so only the spoken value is read.