ki-rating
@kimen/elements/ki-rating- Source
- Agent reference
Use readonly to show an average. The visible number keeps its precision and the artwork rounds to the nearest half star.
<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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Makes an editable rating unavailable and excludes it from form submission. |
icon-name | iconName | string | 'star' | Lucide icon name. Import custom names before mounting. Unavailable names use star. |
label | label | string | – | Visible question in input mode and accessible context in read-only mode. Always supply it. |
max | max | number | 5 | Highest score and number of glyphs. Use a whole number from 1 to 10. |
name | name | string | undefined | – | Form field name for a selected editable score. |
option-label | optionLabel | string | '{value} stars' | Accessible name pattern for the other choices. Use {value} for the choice. |
option-singular-label | optionSingularLabel | string | '{value} star' | Accessible name pattern for the one-star choice. Use {value} for the choice. |
precision | precision | number | 1 | Choose 1 for whole steps or 0.5 for half steps. Other inputs use whole steps. |
rated-label | ratedLabel | string | 'Rated {value} out of {max}' | Accessible name pattern for the read-only image. Use {value} and {max} for the scores. |
readonly | readonly | boolean | false | Displays a score without editing or submitting it. |
required | required | boolean | false | Requires an editable score before the form can be submitted. |
required-message | requiredMessage | string | 'Select a rating.' | Validation message for an unanswered required rating. |
score-label | scoreLabel | string | '{value} of {max}' | Visible score pattern in input mode. Use {value} and {max} for the scores. |
value | value | number | 0 | Current score. Zero means unanswered in input mode. Editable scores use the nearest allowed step. Read-only scores retain their decimal precision. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<{ value: number }> | Fires once when a person changes the selection. The detail contains the numeric value. |
CSS parts
| Part | Description |
|---|---|
choice | Native radio target for one selectable score. |
glyph | Decorative artwork for one rating step. |
label | Visible question above the editable scale. |
scale | Read-only score image or editable radio group. |
score | Visible numeric score. |
CSS custom properties
The public styling contract of ki-rating: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-target-min | The 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-color | Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme. |
--ki-focus-ring-width | Thickness 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-fg | Glyph ink while the rating is unavailable. |
--ki-rating-gap | Space between rating glyphs or targets. |
--ki-rating-hover-backdrop-filter | Complete backdrop filter for the hovered choice. |
--ki-rating-hover-bg | Surface of the choice under the pointer. |
--ki-rating-hover-bg-image | Optional image over the hovered choice surface. |
--ki-rating-label-bg | Backdrop of the visible question. |
--ki-rating-label-fg | Ink of the visible question. |
--ki-rating-label-gap | Space between the question and scale. |
--ki-rating-off-bg | Backdrop of an outlined glyph. |
--ki-rating-off-fg | Ink of an outlined glyph. |
--ki-rating-on-bg | Backdrop of a filled glyph. |
--ki-rating-on-fg | Ink of a filled glyph. |
--ki-rating-score-bg | Backdrop of the visible score. |
--ki-rating-score-fg | Ink of the visible score. |
--ki-rating-score-gap | Space between the glyphs and visible score. |
--ki-rating-size | Size of a rating glyph. |
--ki-rating-target-radius | Corners of the interactive target. |
--ki-rating-target-size | Default whole-step target size. |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-body-1 | semantic dimension for typography line height body 1. |
--ki-typography-size-body-1 | semantic dimension for typography size body 1. |
--ki-typography-weight-body-medium | semantic font weight for typography weight body medium. |