Rate
A star rating supporting keyboard arrow-key adjustment, half-star interaction, hover preview, readonly display, and touch drag; clicking the currently selected star clears the value by default.
Basic Usage
Basic usage
Custom Count
max
Set the number of stars via max.
Half Stars
Half stars (allow-half)
With allow-half, half stars are interactive: clicking the left half of a star rates i-0.5, the right half rates i; keyboard ←/→ step by 0.5.
Hover Preview
Hover preview (oas-hover)
Stars fill with the preview value while hovering (the value is not committed) and oas-hover is dispatched (detail: { value }); leaving the component dispatches detail: { value: null } and the display falls back to the committed value. With allow-half the preview also snaps to 0.5 by half region.
Clear on Click
Clear on click (allow-clear)
allow-clear is enabled by default: clicking the currently selected star again clears it to 0 and dispatches oas-change (detail: { value: 0 }); setting it to "false" disables clearing on click.
Sizes
Sizes (size)
Three size tiers: small (16px) / medium (default, 20px) / large (28px); fine-tune via the --oas-rate-star-size CSS variable; invalid values fall back to medium with a warning.
Custom Icon (icon property)
Custom icon (icon property)
Pass a character or SVG markup via the icon property to replace the star icon:
Custom icon (icon property · SVG)
Custom Icon (slot)
Custom icon (slot)
Pass any element via slot="icon"; it is cloned onto every star. Priority: icon property > slot="icon" > default star.
Dual-State Icons
Dual-state icons (void-icon)
Unselected stars use void-icon (property or slot="void-icon"); selected stars keep the icon channel. A half star renders the void icon as its base and the selected icon as the clipped overlay. Without void customization both states share the same icon and differ only by color (the default outlined star is naturally dual-state).
Per-Value Symbols
Per-value symbols (icons property / slot=icon-N)
Each star can have a different symbol via two channels:
iconsproperty: JSON string array (or propertyel.icons = [...]), per-star override;slot="icon-N": declarative per-position slot (N starts at 1).
Per-star priority: icons[i] > slot="icon-N" > icon property > slot="icon" > default star.
highlight-selected-only switches the fill rule to "only the selected star lights up" — essential for per-value emoji grading (otherwise all stars before the selection light up too).
Emoji Grading
Emoji grading (icons + highlight-selected-only)
The "≤ 2 😞 / ≤ 3 😐 / otherwise 😄" graded-expression effect needs no component-level switch — combine per-value icons with highlight-selected-only (click the rating above to switch expressions).
Custom Colors
Custom colors (color / void-color)
color sets the active star color and void-color the inactive one; both support the 11 preset names (mapped to --oas-preset-*, dark-adaptive) and any CSS color value. Defaults fall back to the --oas-color-warning-text / --oas-color-border tokens (also customizable in bulk via the --oas-rate-active / --oas-rate-void variables).
Threshold Segment Colors
Threshold segment colors (colors)
colors changes color by score segment (low scores red, high green): a JSON string array or property el.colors = [...]; segment boundaries divide max evenly (3 colors = thirds), and the hover preview follows. Priority: colors > color > default tokens.
Auxiliary Text
Auxiliary text (texts + show-text)
show-text displays the text for the current score on the right; texts is comma-separated (half values take the ceil tier). When texts is set, aria-valuetext is synchronized for screen readers.
Score Display
Score display (show-score + score-template)
show-score displays the score on the right; score-template uses the {value} placeholder (defaults to the plain number). When both are set, show-score takes precedence over show-text.
Readonly
Readonly (readonly)
readonly is independent of disabled: no dimming, no response to click/keyboard/hover preview; the value displays normally and still submits with the form system (aria-readonly synchronized). Readonly display supports arbitrary decimals (e.g. 3.7 renders by overlay width). disabled dims the control and expresses the disabled semantic instead.
Disabled
Disabled
Per-Star Tooltips
Per-star tooltips (tooltips)
tooltips is a comma-separated per-star text list; hovering a star shows a floating tip (light oas-tooltip integration with viewport-coordinate positioning). Stars beyond the list length show no tip.
Touch Drag
Touch drag (slide to rate)
On touch devices, press and slide to rate continuously (0.5 granularity by half region with allow-half); the synthetic click after dragging never triggers the clear-on-click path. Desktop mice keep the hover-preview + click path. Try it on a touch device.
Events
Change events
Listen to oas-change (on click, clear, or keyboard adjustment, detail: { value }):
API
oas-rate
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
allow-clear | Clear to 0 when clicking the currently selected star | string | true |
allow-half | Allow half stars | boolean | — |
color | Selected color (preset name or any CSS color) | — | — |
colors | Threshold colors as a JSON array (segments split evenly across max, e.g. ["#f5222d","#faad14","#52c41a"] for three bands) | string[] | null | — |
disabled | Disabled | boolean | — |
highlight-selected-only | Highlight only the selected star (others stay unselected-colored) | boolean | — |
icon | Custom star icon (character or SVG markup) | — | — |
icons | Per-value icons as a JSON array (a different icon per value, e.g. grading 😞😞😐😄😄; arrays may also be assigned via property) | string[] | null | — |
max | Number of stars | string | 5 |
readonly | Read-only (independent of disabled: non-interactive, normally displayed, still submitted with the form) | boolean | — |
score-template | Score template string with a {value} placeholder (e.g. "{value} points"); takes precedence over show-text | string | {value} |
show-score | Show the numeric score in read-only scenarios (pair with score-template) | boolean | — |
show-text | Show the text for the current value (texts) | boolean | — |
size | Size preset small / medium (default 20px) / large (28px) | string | — |
texts | Per-value helper texts (comma-separated, pair with show-text) | — | — |
tooltips | Per-star tooltip texts (comma-separated, shown on star hover; light oas-tooltip integration) | — | — |
value | Current score (controlled) | number | 0 |
void-color | Unselected color | — | — |
void-icon | Unselected icon name (e.g. heart for a ♥/♡ dual state) | — | — |
Property (JS property; see each row for attribute reflection)
| Property | Description | Type | Default |
|---|---|---|---|
value | Current value: the rating score (number) | number | — |
Events
| Event | Description |
|---|---|
oas-change | Score change, detail: { value } |
oas-hover | Fires on star hover, detail: { value }; { value: null } on leave |
Slots
| Name | Description |
|---|---|
icon | Custom icon for the selected state (replaces the default star) |
icon-${i} | Per-index icon override (host writes <span slot="icon-1"> …; i is the 1-based index); icon overrides all |
void-icon | Custom icon for the unselected state (replaces the default star) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-rate-active | var(--oas-color-warning-text) |
--oas-rate-star-size | 20px |
--oas-rate-void | var(--oas-color-border) |
Icon customization: icon property > slot="icon" (cloned to each star) > default star.
Keyboard: ←/→ (or ↑/↓) to adjust, Home to reset to zero, End to fill.