Skip to content
Nana UI

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.

View .md Download

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add rating --framework web-components
npx @nana-tec/ui add rating --framework svelte

Lands in src/lib/components/ui/rating/ as NanaRating.svelte, styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

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.

<nana-rating value="3"></nana-rating>

precision="half" enables half-stars; show-value shows the number; readonly / disabled make it non-interactive.

The variant attribute sets the symbol — star (default), heart, or circle.

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.

Properties

PropertyAttributeTypeDefaultDescription
ariaLabelaria-labelstring | nullnullAccessible label
clearableclearablebooleanfalseClicking the current value resets it to zero
disableddisabledbooleanfalseDisable interaction and dim the control
errorMessageerror-messagestring''Error under the field while it is invalid, in the error part with role="alert".
invalidinvalidbooleanfalseMarks the field invalid and shows error-message in place of the helper text.
maxmaxnumber5Number of symbols
precisionprecisionRatingPrecision'full'Selection granularity
readonlyreadonlybooleanfalseDisplay only — no interaction
showValueshow-valuebooleanfalseShow the numeric value beside the symbols
sizesizeSize'md'Component size
valuevaluenumber0Current rating value
variantvariantRatingVariant'star'Symbol shape

Events

EventDescription
nana-changeFired when the value is committed (detail.value)
nana-inputFired while hovering over a new value (detail.value)

CSS parts

PartDescription
::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

PropertyDescription
--nana-rating-colorActive symbol colour
--nana-rating-empty-colorEmpty symbol colour
--nana-rating-sizeSymbol size (overrides size)
--nana-rating-gapGap between symbols

NanaRating

PropTypeDefault
valuebind:number0
maxnumber5
precisionRatingPrecision'full'
variantRatingVariant'star'
sizeRatingSize'md'
labelstring'Rating'
readonlybooleanfalse
disabledbooleanfalse
clearablebooleanfalse
showValuebooleanfalse
invalidbooleanfalse
errorMessagestring
onValueChange(value: number) => void

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.