HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
RatingView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA row of marks, such as stars, for giving or showing a score.StableSince 0.1.0FormsUsageimport'@fusion.dev/helix/rating'import'@fusion.dev/helix-headless/rating'Preview
API ReferenceRoothelix-ratingA row of marks, such as stars, for giving or showing a score.
PropTypeDescriptionclearablebooleanDefaultfalseWhether a reader can take the rating back to unrated: by pressing the
chosen score again, or with Backspace or Delete. Zag's rating group
clears the same way.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.maxnumberDefault5How many marks there are.minnumberDefault0The lowest score that can be given. A cleared rating shows this score.namestringDefault""The name the control's value is submitted under.optionLabelstringDefault"{score} out of {max}"The name of each mark a reader can choose, with {score} and {max}
filled in, written in the locale. Set it to translate "3 out of 5".readOnlybooleanDefaultfalseShows the score without letting users change it.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.shape"dots"The shape of each mark. dots draws plain circles.showValuebooleanDefaultfalseShows the score as a number next to the marks.stepnumberDefault1The smallest part of a mark that can be chosen.valuestringThe control's current value, which its form submits.valueAsNumbernumberThe value as a number, or NaN while the control is empty.valueMissingMessagestringDefault"Choose a rating to continue."The message shown when the field is required and empty.valueTextstringDefault""The text screen readers read for the score, in place of "3.5 out of 5".
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.scorenumberThe score, as a number, clamped to what the marks can show.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionempty-markThe shape of an unfilled mark, copied into every position of the track, such as an outlined star beside a filled mark. Without it, the track copies mark.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.labelThe label, for content richer than the label text.markThe shape of a mark, copied into every position. When the slot is empty, the stylesheet draws a mark, and --rating-mark changes its shape.
EventTypeDescriptionchangeEventThe score was chosen. Sent together with input, because each choice commits the score.helix-before-changeHelixBeforeChangeEventThe score is about to change. Cancelable: cancel it to keep the current score.helix-clearHelixClearEventThe rating went back to unrated, under clearable. Sent after input and change.helix-previewHelixPreviewEventThe score under the pointer, shown before it is chosen, or '' once the marks show the score again. Sent once each time the preview changes.inputEventThe score changed.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionfeedbackThe message that says what is wrong.fieldThe row that holds the marks and the score next to them.fillThe filled marks, clipped to the score.hintHelp text under the marks, shown while there is no feedback.labelThe label above the marks.markOne mark, in the fill or the track.marksThe row of marks.optionOne target you can press, for one step.trackThe unfilled marks.valueThe score as a number, shown with show-value.
CSS PropertyDescription--rating-colorThe color of a filled mark.--rating-empty-colorThe color of an unfilled mark.--rating-fullThe number of marks that are fully filled.--rating-gapThe space between marks.--rating-markThe shape of one mark, as a mask image.--rating-partHow much of the next mark is filled, from 0 to 1.--rating-sizeThe size of one mark.--rating-stepThe target's position among all the steps in the row, counting from one. Steps below min still count.--rating-stepsThe number of steps in the whole row: max divided by step.
Custom stateDescriptioninvalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-ratingA row of marks, such as stars, for giving or showing a score.
PropTypeDescriptionclearablebooleanDefaultfalseWhether a reader can take the rating back to unrated: by pressing the
chosen score again, or with Backspace or Delete. Zag's rating group
clears the same way.defaultValuestringDefault""The value the control starts with. A form reset returns it to this value,
and to the value attribute where this one is not written, as a native
control resets to the value it declares.disabledbooleanDefaultfalseWhether the control is disabled and cannot be used.feedbackstringDefault""The validation message shown under the control. It replaces the
browser's message.hintstringDefault""Help text shown under the control. A validation message replaces it.labelstringDefault""The field's label, which is also its accessible name. Content in the
label slot replaces it.maxnumberDefault5How many marks there are.minnumberDefault0The lowest score that can be given. A cleared rating shows this score.namestringDefault""The name the control's value is submitted under.optionLabelstringDefault"{score} out of {max}"The name of each mark a reader can choose, with {score} and {max}
filled in, written in the locale. Set it to translate "3 out of 5".readOnlybooleanDefaultfalseShows the score without letting users change it.requiredbooleanDefaultfalseWhether the field needs a value before the form can submit.showValuebooleanDefaultfalseShows the score as a number next to the marks.stepnumberDefault1The smallest part of a mark that can be chosen.valuestringThe control's current value, which its form submits.valueAsNumbernumberThe value as a number, or NaN while the control is empty.valueMissingMessagestringDefault"Choose a rating to continue."The message reported when the field is required and no rating is chosen.
Absent, or empty, is this sentence, or the words registered for the page's
locale.valueTextstringDefault""The text screen readers read for the score, in place of "3.5 out of 5".
ReadTypeDescriptionformHTMLFormElement|nullThe form the control belongs to, or null.labelsNodeListThe labels associated with the control.scorenumberThe score, as a number, clamped to what the marks can show.validationMessagestringThe message the browser would show for the control, or an empty string.validityValidityStateWhether the control meets its constraints, and why not.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.willValidatebooleanWhether the control is checked when its form is submitted.
SlotDescriptionempty-markThe shape of an unfilled mark, copied into every position of the track, such as an outlined star beside a filled mark. Without it, the track copies mark.feedbackThe message that says what is wrong, for content richer than a string. It shows while there is a message.hintHelp under the control, for content richer than the hint text.labelThe label, for content richer than the label text.markThe shape of a mark, copied into every position.
EventTypeDescriptionchangeEventThe score was chosen. Sent together with input, because each choice commits the score.helix-before-changeHelixBeforeChangeEventThe score is about to change. Cancelable: cancel it to keep the current score.helix-clearHelixClearEventThe rating went back to unrated, under clearable. Sent after input and change.helix-previewHelixPreviewEventThe score under the pointer, shown before it is chosen, or '' once the marks show the score again. Sent once each time the preview changes.inputEventThe score changed.
MethodTypeDescriptioncheckValidity() => booleanReturns whether the control is valid, and fires invalid on it when it is
not. The control shows no message for it: reportValidity() does that.focus(options: FocusOptions) => voidMoves focus to the control, as focusing a native control does.reportValidity() => booleanReturns whether the control is valid, and when it is not, fires invalid
and shows the browser's message at the control.requestValue(next: string) => booleanRequests a new value, and returns whether the change was applied.setCustomValidity(message: string) => voidMarks the control invalid with message, or clears that with an empty
string, as on a native control. The form does not submit while it is set.
PartDescriptionfeedbackThe message that says what is wrong.fieldThe row that holds the marks and the score next to them.fillThe filled marks, clipped to the score.hintHelp text under the marks, shown while there is no feedback.labelThe label above the marks.markOne mark, in the fill or the track.marksThe row of marks.optionOne target you can press, for one step.trackThe unfilled marks.valueThe score as a number, shown with show-value.
CSS PropertyDescription--rating-fullThe number of marks that are fully filled.--rating-partHow much of the next mark is filled, from 0 to 1.--rating-stepThe target's position among all the steps in the row, counting from one. Steps below min still count.--rating-stepsThe number of steps in the whole row: max divided by step.
Custom stateDescriptioninvalidThe control has an error to show, from the browser's validation or from your feedback.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCustom MarkA custom shape in the mark slot, copied into every position, including half marks.DotsPlain circles, for a level such as how spicy a dish is.EventsOne set of events per chosen score. A drag sends nothing until it is released.HalvesHalf marks, with step set to 0.5.In A FieldA rating as a form control, with help under it and a message when it is missing.PreviewA score out of five, set by pointer or by arrow key.PreviewA score out of five, set by pointer or by arrow key.Read OnlyA read-only rating that shows an average score.Review SummaryA review summary, with the average as a read-only rating and the spread as meters.Show ValueThe score shown as marks and as a number.