HyRating

Usage examples on this page are written for Lit / plain HTML (<hy-rating>). The same component ships as HyRating in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A form-associated star-rating control. Renders max symbols and fills them to express a numeric value, supporting whole, half, and arbitrary fractional fill via clip-path. Slider semantics over a discrete range — a visually-hidden native <input type="range"> owns keyboard navigation, focus, aria-valuenow/min/max, and form participation; the star chrome is a custom visual layer with its own pointer (hover-preview + click) handling.

Form Integration

Implements the Form-Associated Custom Elements API — the rating's value is included in FormData when the form is submitted under its name.

Keyboard

The native range input handles arrow keys (step by precision), Home / End (min / max). Digit keys 1…max jump to that rating; 0 clears (when clearable).

Fractional display

precision constrains only interactive stops. A read-only value of any fraction (e.g. an average of 3.7) always renders accurately via clip-path.

When to use

• Collecting a quick score: a review, a satisfaction survey, feedback on an answer.
• Showing an average score, with readonly.

Do

• Use the same max everywhere in the product.
• Show the number of ratings next to an average.

When not to use

• A precise score, such as one out of 100: hy-number-input or hy-slider.
• Pass or fail, risk or health: a hy-badge or hy-chip, or hy-progress for a level.
• Yes or no, like or dislike: one hy-toggle, or two buttons.
• Options with names that carry meaning ("Poor", "Fair", "Good"): hy-radio-group with visible labels.

Accessibility: your part

• Next to a read-only average, show the figure and the count as text ("3.7, 128 reviews"). Partial stars are hard to read.
• When the scale is not obvious, say in nearby text what it measures.

Examples

Basic usage

<hy-rating label="Quality" value="3"></hy-rating>

Half-star precision

<hy-rating label="Score" precision="0.5" value="2.5"></hy-rating>

Read-only average

<hy-rating label="Average" readonly value="3.7"></hy-rating>

Form submission

<form>
  <hy-rating name="stars" label="Rate us" value="4"></hy-rating>
  <button type="submit">Save</button>
</form>

API

Properties

Property	Attribute	Type	Default	Description
value	value	number	0	The current rating. 0 = unrated.
max	max	number	5	Number of symbols.
precision	precision	1 | 0.5	1	Interactive granularity: 1 (whole symbols) or 0.5 (half symbols). Display of arbitrary fractional values is always supported via clip-path; precision only constrains the interactive stops.
readonly	readonly	boolean	false	Display-only. Any fractional value still renders; interaction is blocked.
disabled	disabled	boolean	false	Non-interactive + dimmed; excluded from form submission.
size	size	'small' | 'medium' | 'large'	'medium'	Symbol size.
variant	variant	'default' | 'brand'	'default'	Filled-symbol color. default resolves to the warning (rating-gold) role.
clearable	clearable	boolean	false	Re-selecting the current value (or Home / 0) clears to 0.
icon	icon	string	'star'	System icon name for the symbol (e.g. heart).
label	label	string	''	Accessible name. Also honors aria-label / aria-labelledby on the host.
valueLabel	value-label	string	'{value} out of {count, plural, one {# star} other {# stars}}'	Announced value (aria-valuetext), a template: {value} is the rating and {count} the number of symbols, both in the locale's digits; a plural choice on either picks the word's form in the locale (French agrees with the rating: {value, plural, one {# étoile} other {# étoiles}} sur {count}). Use for internationalization.
name	name	string	''	Form field name.
autofocus	autofocus	boolean	false	Marks this rating as the auto-focus target. Read by hy-dialog (and other overlay containers) on show. Also focuses on first connect when used outside an overlay, mirroring native HTML autofocus but routed through JS so SSR'd HTML doesn't pull focus during hydration.
form	—	HTMLFormElement | null	—	Returns the form element that contains this rating, if any.
validity	—	ValidityState	—	Returns the ValidityState object for the rating.
validationMessage	—	string	—	Returns the validation message for the rating.

Events

Event	Detail	Description
input	—	Fired during interactive change (hover-commit / keyboard). Detail: { value: number }
change	—	Fired when the value is committed (click / keyboard). Detail: { value: number }

CSS Parts

Part	Description
base	The component's outer wrapper
label	The label element
input	The native range input (visually hidden, interaction-only)
control	The symbol row (pointer target)
symbol	An individual symbol cell

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-rating-icon-size-md	var(--hy-icon-size-md)	Symbol (icon) size. Defaults to a per-size icon-size token.
--hy-rating-icon-size-sm	var(--hy-icon-size-sm)	Symbol (icon) size. Defaults to a per-size icon-size token.
--hy-rating-icon-size-lg	var(--hy-icon-size-lg)	Symbol (icon) size. Defaults to a per-size icon-size token.
--hy-rating-gap-layout-2xs	var(--hy-gap-layout-2xs)	Gap between symbols.
--hy-rating-foreground-warning-rest	var(--hy-foreground-warning-rest)	Filled-symbol color. Defaults per variant.
--hy-rating-foreground-brand-rest	var(--hy-foreground-brand-rest)	Filled-symbol color. Defaults per variant.
--hy-rating-foreground-faint-rest	var(--hy-foreground-faint-rest)	Empty-symbol color.
--hy-rating-foreground-default-disabled	var(--hy-foreground-default-disabled)	Filled-symbol color when disabled.
--hy-rating-background-neutral-disabled	var(--hy-background-neutral-disabled)	Empty-symbol color when disabled (the disabled fill: the empty symbols are the track).
--hy-rating-label-foreground-default-disabled	var(--hy-foreground-default-disabled)	Label color when disabled.

Methods

checkValidity()

Checks if the rating's current value satisfies its constraints.

reportValidity()

Checks validity and reports any errors to the user.

focus()

Focuses the underlying range input.

blur()

Removes focus from the underlying range input.