Rating

Stars for feedback moments.

<sui-rating>Advanced inputsStable

About

Star rating for feedback moments such as a post-support survey or a CSAT prompt. Orange stars fill on hover as a preview, and picking the selected star again clears the rating. Not for financial data, where a number belongs in a field.

Usage

<sui-rating label="How was reconciliation?" name="csat" value="4" show-count help="Feedback goes to the support team."></sui-rating> <script type="module"> import { defineCustomElements } from "@shineui/core/loader"; import "@shineui/core/shineui.css"; defineCustomElements(); const el = document.querySelector("sui-rating"); el.addEventListener("suiChange", (e) => console.log(e.detail)); </script>

import { SuiRating } from "@shineui/react"; import "@shineui/core/shineui.css"; export function Example() { return <SuiRating label="How was reconciliation?" name="csat" value="4" showCount help="Feedback goes to the support team." onSuiChange={(e) => console.log(e.detail)} />; }

import { Component } from "@angular/core"; import { SuiRating } from "@shineui/angular"; @Component({ standalone: true, imports: [SuiRating], template: `<sui-rating label="How was reconciliation?" name="csat" value="4" show-count help="Feedback goes to the support team." (suiChange)="onChange($event)"></sui-rating>`, }) export class Example { onChange(e: CustomEvent) { console.log(e.detail); } }

Basic

The stars are a role="radiogroup" and only the selected star is tabbable, so Tab lands on the current value. Clicking the selected star clears the rating.

<sui-rating label="How was reconciliation?" name="csat" value="4" show-count help="Feedback goes to the support team."></sui-rating>

Half stars

allow-half picks a half from the leading side of a star, steps by a half on the arrow keys, and posts the decimal. The checked star reads "3.5 of 5" to a screen reader.

Sizes and counts

Star size is sm 13px, md 16px and lg 20px. count sets how many stars render; the aria-label on each star reads "3 of 5".

States

readonly keeps the rated star in the tab order and announces read-only, as a native read-only input stays focusable, while a click, the arrows and the hover preview change nothing; disabled leaves the tab order. Neither holds the form on valueMissing, because a user cannot clear an error they cannot change.

In a form

A rated control posts the number and an unrated one posts an empty string. required holds the form until a star is picked.

<form id="rt-form" style="display:grid;gap:14px;justify-items:start"> <sui-rating label="How was reconciliation?" name="csat" required></sui-rating> <sui-rating label="How was the support reply?" name="support" value="4"></sui-rating> <sui-button type="submit" variant="brand" label="Send feedback"></sui-button> <output id="rt-form-out" style="font:460 13px/1.6 var(--font-sans);color:var(--ink-muted)">Submit to see what posts.</output> </form>

// setup(root): properties and events setup(root) { const form = root.querySelector('#rt-form'); const out = root.querySelector('#rt-form-out'); form.addEventListener('submit', (e) => { e.preventDefault(); out.textContent = [...new FormData(form)].map(([k, v]) => `${k}=${v}`).join(' '); }); }

Events

suiChange carries the new value. Clicking the selected star clears the rating and reports 0.

Idle.

// setup(root): properties and events setup(root) { const el = root.querySelector('#rt-events'); const log = root.querySelector('#rt-log'); el.addEventListener('suiChange', (e) => { log.textContent = e.detail === 0 ? 'suiChange 0. Rating cleared.' : `suiChange ${e.detail}.`; }); }

Keyboard

Key	Action
`Tab`	Moves to the rated star, or to the first star when nothing is rated. A read-only rating keeps this stop and announces read-only; a disabled one is passed over.
`ArrowRight` `ArrowUp`	Raises the rating one star, or a half with allow-half, and moves focus with it. Under dir="rtl" the pair swaps, so the arrow that points along the reading direction is always the forward one.
`ArrowLeft` `ArrowDown`	Lowers it by the same step, stopping at the lowest rating, never at none.
`Home` `End`	Jumps to the lowest rating or to all the stars.
`Enter` `Space`	Picks the focused star, or clears the rating when that star is already selected.

API

`<sui-rating>`

Properties

Property	Attribute	Type	Default	Description
`allowHalf`	`allow-half`	`boolean`	`false`	Half stars. The leading half of a star (its left, or its right under `dir="rtl"`) picks `n.5`, the arrow keys step by a half, and the value and the posted form entry carry the decimal (`2.5`). Without it a decimal value rounds up on screen to the next whole star.
`count`	`count`	`number`	`5`	Number of stars.
`disabled`	`disabled`	`boolean`	`false`	Disables the stars. A disabled rating posts nothing and never holds the form.
`error`	`error`	`string`string \| undefined		Error message under the stars; also sets aria-invalid.
`help`	`help`	`string`string \| undefined		Help text under the stars. Replaced by `error` when set.
`label`	`label`	`string`string \| undefined		Label before the stars; also names the radiogroup.
`name`	`name`	`string`string \| undefined		Form control name. Posts the number, or an empty string while nothing is rated; a disabled rating posts nothing. Reflected: entry construction reads the content attribute, and the three framework bindings set props, so an unreflected name would post nothing.
`readOnly`	`readonly`	`boolean`	`false`	Display only, as a native read-only input: the rated star keeps its tab stop and the stars announce read-only, but a click, the hover preview and the arrow keys change nothing, and the value still posts. A disabled rating, unlike it, leaves the tab order.
`required`	`required`	`boolean`	`false`	A rating must be picked for the surrounding form to be valid. A read-only or disabled rating never holds the form, since the user could not clear the error.
`showCount`	`show-count`	`boolean`	`false`	Shows "4 of 5" after the stars. Its words are translatable (`rating.count`, `{value} of {count}`) and its figures follow the page's locale, so a half star reads "2,5" in German.
`size`	`size`	`"lg" \| "md" \| "sm"`	`'md'`	Star size: sm 13px, md 16px, lg 20px.
`value`	`value`	`number`	`0`	Current rating, 0 = none. Mutable; updated before `suiChange` fires.

Events

Event	Detail	React	Vue	Description
`suiChange`	`number`	`onSuiChange`	`@sui-change`	Fires when the rating changes; detail is the new value (0 after clearing, `n.5` for a half star).

Methods

Method	Signature	Description
`setFocus()`	`setFocus() => Promise<void>`	Moves keyboard focus to the star that holds the tab stop, as `el.focus()` does: the rated one, or the first when nothing is rated. sui-form calls this to reach the first invalid control.

Theming

Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.