Skip to content
Kimenpre-v1documentation home
Color scheme

ki-rating

Use readonly to show an average. The visible number keeps its precision and the artwork rounds to the nearest half star.

Theme for this example
Color scheme for this example
<ki-rating readonly label="Average review score" value="4.3"></ki-rating>

Give an editable rating a question in label. Tab enters the group, arrows move and select, and Space selects the focused option. Choose precision="0.5" to make both halves of each star selectable.

Theme for this example
Color scheme for this example
<ki-rating label="How useful was this answer?" precision="0.5" value="2.5"></ki-rating>

Use name to include a selected score in form data and required to require an answer. Listen for ki-change and read the numeric score from event.detail.value.

API reference

When to use: Show an average review score in readonly mode or ask people to rate an answer, experience, or product on a small scale.

When not to use: Use message actions for yes/no feedback and a slider for a continuous or large numeric range.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseMakes an editable rating unavailable and excludes it from form submission.
icon-nameiconNamestring'star'Lucide icon name. Import custom names before mounting. Unavailable names use star.
labellabelstring–Visible question in input mode and accessible context in read-only mode. Always supply it.
maxmaxnumber5Highest score and number of glyphs. Use a whole number from 1 to 10.
namenamestring | undefined–Form field name for a selected editable score.
option-labeloptionLabelstring'{value} stars'Accessible name pattern for the other choices. Use {value} for the choice.
option-singular-labeloptionSingularLabelstring'{value} star'Accessible name pattern for the one-star choice. Use {value} for the choice.
precisionprecisionnumber1Choose 1 for whole steps or 0.5 for half steps. Other inputs use whole steps.
rated-labelratedLabelstring'Rated {value} out of {max}'Accessible name pattern for the read-only image. Use {value} and {max} for the scores.
readonlyreadonlybooleanfalseDisplays a score without editing or submitting it.
requiredrequiredbooleanfalseRequires an editable score before the form can be submitted.
required-messagerequiredMessagestring'Select a rating.'Validation message for an unanswered required rating.
score-labelscoreLabelstring'{value} of {max}'Visible score pattern in input mode. Use {value} and {max} for the scores.
valuevaluenumber0Current score. Zero means unanswered in input mode. Editable scores use the nearest allowed step. Read-only scores retain their decimal precision.

Events

EventDetail typeDescription
ki-changeCustomEvent<{ value: number }>Fires once when a person changes the selection. The detail contains the numeric value.

CSS parts

PartDescription
choiceNative radio target for one selectable score.
glyphDecorative artwork for one rating step.
labelVisible question above the editable scale.
scaleRead-only score image or editable radio group.
scoreVisible numeric score.

CSS custom properties

The public styling contract of ki-rating: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-rating-disabled-fgGlyph ink while the rating is unavailable.
--ki-rating-gapSpace between rating glyphs or targets.
--ki-rating-hover-backdrop-filterComplete backdrop filter for the hovered choice.
--ki-rating-hover-bgSurface of the choice under the pointer.
--ki-rating-hover-bg-imageOptional image over the hovered choice surface.
--ki-rating-label-bgBackdrop of the visible question.
--ki-rating-label-fgInk of the visible question.
--ki-rating-label-gapSpace between the question and scale.
--ki-rating-off-bgBackdrop of an outlined glyph.
--ki-rating-off-fgInk of an outlined glyph.
--ki-rating-on-bgBackdrop of a filled glyph.
--ki-rating-on-fgInk of a filled glyph.
--ki-rating-score-bgBackdrop of the visible score.
--ki-rating-score-fgInk of the visible score.
--ki-rating-score-gapSpace between the glyphs and visible score.
--ki-rating-sizeSize of a rating glyph.
--ki-rating-target-radiusCorners of the interactive target.
--ki-rating-target-sizeDefault whole-step target size.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-weight-body-mediumsemantic font weight for typography weight body medium.

Workshop

Open ki-rating in Storybook