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.

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	RatingPrecision	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.
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

Property	Description
--hy-rating-symbol-size	Symbol (icon) size. Defaults to a per-size icon-size token.
--hy-rating-gap	Gap between symbols.
--hy-rating-fill-color	Filled-symbol color. Defaults per variant.
--hy-rating-empty-color	Empty-symbol color.

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.