Forms & Inputs
Rating
A rating component for displaying and collecting star (or heart/dot) ratings. Supports fractional display, half- and full-step input, multiple symbols, read-only and disabled states, sizes, hover preview, keyboard control and an optional value label.
Preview
Section titled “Preview”<nana-rating value="3"></nana-rating> <script lang="ts">
import { NanaRating } from '$lib/components/ui/rating';
let score = $state(3.5);
</script>
<div class="flex flex-col items-start gap-3">
<NanaRating bind:value={score} precision="half" showValue label="Your rating" />
<NanaRating value={4} variant="heart" size="sm" readonly />
</div> Installation
Section titled “Installation”Install the package for a versioned dependency:
npm install @nana-tec/ui-componentsOr copy the source in and own it:
npx @nana-tec/ui add rating --framework web-componentsnpx @nana-tec/ui add rating --framework svelteLands in src/lib/components/ui/rating/ as NanaRating.svelte, styled with Tailwind
classes that resolve to the design tokens. Requires Tailwind v4.
Import
Section titled “Import”
Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and
each component downloads only the first time a page uses it:
import "@nana-tec/ui-components/autoloader";import "@nana-tec/ui-components/theme";The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.
Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:
import "@nana-tec/ui-components/rating";
Copied in with npx @nana-tec/ui add rating? Import your project's own
@/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.
<script lang="ts"> import { NanaRating } from '$lib/components/ui/rating';
let score = $state(0);</script>
<NanaRating bind:value={score} precision="half" clearable label="Rate this unit" />A slider for screen readers (“3.5 of 5”); arrows, Home and End move it.
With precision="half" the left half of a star picks a half. clearable lets a second
click on the current value reset it to zero.
Basic usage
Section titled “Basic usage”<nana-rating value="3"></nana-rating><nana-rating size="sm" value="3"></nana-rating>
<nana-rating size="md" value="3"></nana-rating>
<nana-rating size="lg" value="3"></nana-rating> Precision & states
Section titled “Precision & states”precision="half" enables half-stars; show-value shows the number;
readonly / disabled make it non-interactive.
<nana-rating value="3.5" precision="half" show-value></nana-rating>
<nana-rating value="4.5" precision="half" readonly show-value></nana-rating>
<nana-rating value="2" disabled></nana-rating>
<nana-rating value="6" max="10" show-value></nana-rating> Icon variants
Section titled “Icon variants”The variant attribute sets the symbol — star (default), heart, or circle.
<nana-rating value="3" variant="star"></nana-rating>
<nana-rating value="3" variant="heart"></nana-rating>
<nana-rating value="3" variant="circle"></nana-rating> Errors
Section titled “Errors”Set invalid to mark it invalid. error-message shows beneath it only while invalid is set, and is linked to the control as its description.
<nana-rating
aria-label="Your rating"
value="0"
invalid
error-message="Choose a rating."
></nana-rating> Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
ariaLabel | aria-label | string | null | null | Accessible label |
clearable | clearable | boolean | false | Clicking the current value resets it to zero |
disabled | disabled | boolean | false | Disable interaction and dim the control |
errorMessage | error-message | string | '' | Error under the field while it is invalid, in the error part with role="alert". |
invalid | invalid | boolean | false | Marks the field invalid and shows error-message in place of the helper text. |
max | max | number | 5 | Number of symbols |
precision | precision | RatingPrecision | 'full' | Selection granularity |
readonly | readonly | boolean | false | Display only — no interaction |
showValue | show-value | boolean | false | Show the numeric value beside the symbols |
size | size | Size | 'md' | Component size |
value | value | number | 0 | Current rating value |
variant | variant | RatingVariant | 'star' | Symbol shape |
Events
| Event | Description |
|---|---|
nana-change | Fired when the value is committed (detail.value) |
nana-input | Fired while hovering over a new value (detail.value) |
CSS parts
| Part | Description |
|---|---|
::part(base) | The root container |
::part(symbols) | The symbol group |
::part(symbol) | A single rating symbol |
::part(label) | The value label |
::part(error) | The error message, shown while invalid is set |
CSS custom properties
| Property | Description |
|---|---|
--nana-rating-color | Active symbol colour |
--nana-rating-empty-color | Empty symbol colour |
--nana-rating-size | Symbol size (overrides size) |
--nana-rating-gap | Gap between symbols |
NanaRating
| Prop | Type | Default |
|---|---|---|
valuebind: | number | 0 |
max | number | 5 |
precision | RatingPrecision | 'full' |
variant | RatingVariant | 'star' |
size | RatingSize | 'md' |
label | string | 'Rating' |
readonly | boolean | false |
disabled | boolean | false |
clearable | boolean | false |
showValue | boolean | false |
invalid | boolean | false |
errorMessage | string | |
onValueChange | (value: number) => void |
Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.