Star ratings, one file.

API reference

The complete Rating API — constructor modes, every option, instance methods, statics, events, declarative attributes, theming and accessibility.

Constructor & usage

new Rating(target, options?)     // → instance
Rating.create(target, options?)  // same as new

target is a selector string or an element, in one of two modes:

• Container mode — any element: the widget is built inside it. Give name to get a hidden input for form submission, and an aria-label on the container to name the slider.
• Input mode — an existing <input>: it is hidden and kept in sync (so the form still submits it and native change events still fire), and fully restored on destroy(). Its current value seeds the rating (unless value is passed explicitly), its disabled state is inherited, and a <label for> pointing at it becomes the widget's accessible name.

The submitted value is the number as text ("3.5"), or the empty string when the rating is 0/cleared. Constructing on an element that already holds an instance destroys the old one first; a missing target throws; without a DOM (SSR) the constructor returns an inert no-op instance.

new Rating('#stars', { onChange: (v) => console.log(v) })

<input id="score" name="score" value="3">
new Rating('#score')   // submits score=3.5

Options

Every key of Rating.defaults, with its default value.

Methods

Statics & helpers

Events & callbacks

• onChange(value) — the committed value, after click, keyboard, or a non-silent setValue() that changed the value.
• onHover(value | null) — the preview value while hovering, null on leave (the committed value is repainted).
• rating:change — a bubbling CustomEvent dispatched from the widget root on every committed change, with detail: { value, rating }.
• In input mode, every commit also fires a bubbling native-style change event on the enhanced input, like a user edit would.

document.getElementById('stars').addEventListener('rating:change', (e) => {
  console.log(e.detail.value)   // the new value
  console.log(e.detail.rating)  // the instance
})

Declarative init

Add data-vrt to a container or input — instances are built on DOMContentLoaded (or call Rating.autoInit(root) after inserting markup).

<div data-vrt data-value="3.5" data-name="score"></div>

Theming

Auto light/dark with the family's resolution order: <html data-theme> / data-bs-theme / .dark class → prefers-color-scheme, re-resolved live. Pin per instance with theme: 'dark'. All colors are CSS custom properties; Rating is the one family component with a non-accent fill color — a warm star gold — themeable separately:

.vrt {
  --vrt-fill: #f5a623;    /* the star fill (gold; dark theme: #f7b84d) */
  --vrt-accent: #5b5bd6;  /* focus ring */
  --vrt-text: …; --vrt-muted: …; --vrt-faint: …;
  --vrt-radius: 8px; --vrt-font: …;
}

With the VC core loaded, VC.config({ accent: '#b45309' }) themes the focus ring and every other family component in one call (the gold fill stays put unless you override --vrt-fill). Widgets render as class="vrt vc1"; structural rules ship salted so host design systems can't override them, while the unsalted --vrt-* variable definitions keep page overrides working. Change the token with Rating.salt = 'acme' (or false) before the first instance.

Headless: Rating.defaults.styles = false (or per instance) injects no CSS — you keep the full behavior (hover preview, keyboard, ARIA, form sync) and style this markup contract yourself (Rating.css is the reference stylesheet as a string):

.vrt[data-theme=dark].vrt-readonly.vrt-disabled
  .vrt-stars[role=slider|img]      ← .vrt-static when non-interactive
    .vrt-star                      ← × max, sized inline
      .vrt-star-empty              ← outline SVG
      .vrt-star-fill               ← overlay clipped to N% width
        .vrt-star-full             ← filled SVG, fixed width
  .vrt-value                       ← only when showValue
  input[type=hidden]               ← only when name given (container mode)

Accessibility

The whole group is a single tab stop with role="slider", aria-orientation="horizontal", aria-valuemin/max/now and an aria-valuetext built by labels (e.g. "3.5 of 5").

• readOnly renders role="img" with the labels text and takes no focus stop.
• disable() keeps the slider out of the tab order (tabindex="-1", aria-disabled="true").
• In input mode a <label for> pointing at the original input is adopted as the slider's accessible name; in container mode put an aria-label on the container.
• Any fraction renders exactly — the fill is a clipped overlay whose width is a percentage — while interaction still snaps to steps. Reduced motion is respected (the hover scale transition is disabled).

Headless mode

With styles: false Rating injects no CSS at all — the full behavior (hover preview, keyboard, form sync), the role="slider" ARIA contract and the stable .vrt-* class hooks all remain; you bring the stylesheet. The demos below each run in their own <iframe>: the styled examples above have already injected the component stylesheet into this page, so only a separate, clean document can show what headless truly looks like.

new Rating('#stars', {
  value: 3.5,
  styles: false,   // ← zero CSS injected
  onChange: function (v) { /* … */ }
})

/* the component injected nothing — this structural minimum
   is the page's own (no colors, no sizes anywhere): */
.vrt-star { display: inline-block; position: relative; }
.vrt-star svg { display: block; width: 100%; height: 100%; }
.vrt-star-empty, .vrt-star-fill { position: absolute; inset: 0; }
.vrt-star-fill { overflow: hidden; }
.vrt-star-full { display: block; height: 100%; }

<style type="text/tailwindcss">
  .vrt        { @apply inline-flex items-center gap-3; }
  .vrt-stars  { @apply inline-flex gap-1 rounded-xl bg-white/70 p-2
                shadow ring-1 ring-rose-100 outline-none
                focus-visible:ring-2 focus-visible:ring-rose-400; }
  .vrt-star   { @apply relative inline-block cursor-pointer text-rose-200
                transition-transform hover:scale-125; }
  .vrt-star svg { @apply block h-full w-full; }
  .vrt-star-empty, .vrt-star-fill { @apply absolute inset-0; }
  .vrt-star-fill  { @apply overflow-hidden text-rose-500 drop-shadow; }
  .vrt-star-full  { @apply block h-full; }
  .vrt-value  { @apply text-sm font-bold tabular-nums text-rose-600; }
</style>