✨ Features

| Feature | Description | | -------------------------- | ----------------------------------------------------------------- | | 🎯 Half-star ratings | Precise 0.5-step ratings with visual half-fill support | | 📐 Size presets | Five built-in sizes — xs · sm · md · lg · xl | | 🎨 Custom colors | Per-state color tokens: empty, filled, hover, half | | 🔌 Icon providers | Lucide, FontAwesome, or bring your own via scoped slot/render fn | | ⌨️ Keyboard navigation | Arrow keys, Home, End, 0–9 — fully operable without mouse | | 🔒 Read-only mode | Display-only ratings for reviews and dashboards | | ♿ WCAG 2.2 accessible | role="group", aria-pressed per star, aria-live counter | | 🔷 TypeScript-first | Full generics, MaybeRefOrGetter<T> reactive options | | ⚡ Zero dependencies | No runtime deps — only Vue 3.5+ as a peer | | 🌐 RTL support | Right-to-left layout via :rtl="true" | | 🔁 Clearable / reset | Built-in clear button and allow-reset-on-reclick behaviour | | 🧩 Slots API | Override icon, counter, and clear button with your own markup |

📦 Installation

# pnpm (recommended)
pnpm add vue-js-star-rating

# npm
npm install vue-js-star-rating

# yarn
yarn add vue-js-star-rating

Requires Vue 3.5+. This package uses defineModel, useTemplateRef, and MaybeRefOrGetter — all stable in Vue 3.5. It has zero runtime dependencies.

🚀 Quick Start

<script setup lang="ts">
import { ref } from 'vue';
import { VueStarRate } from 'vue-js-star-rating';
import 'vue-js-star-rating/dist/style.css';

const rating = ref(0);
</script>

<template>
  <VueStarRate v-model="rating" />
</template>

Global Plugin Registration

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import VueStarRatePlugin from 'vue-js-star-rating';
import 'vue-js-star-rating/dist/style.css';

createApp(App).use(VueStarRatePlugin).mount('#app');

📖 Examples

Half-Star Ratings

<VueStarRate v-model="rating" :allow-half="true" :show-counter="true" />

Size Presets

<!-- Size Presets: xs(16px), sm(20px), md(24px), lg(32px), xl(40px) -->
<VueStarRate v-model="rating" size="xs" />
<VueStarRate v-model="rating" size="sm" />
<VueStarRate v-model="rating" size="md" />
<VueStarRate v-model="rating" size="lg" />
<VueStarRate v-model="rating" size="xl" />

<!-- Custom pixel size -->
<VueStarRate v-model="rating" :icon-size="28" />

Custom Colors

<VueStarRate
  v-model="rating"
  :colors="{
    empty: '#e5e7eb',
    filled: '#fbbf24',
    hover: '#fcd34d',
    half: '#fbbf24',
  }"
/>

Read-only Display

<VueStarRate v-model="rating" :readonly="true" :show-counter="true" />

Clearable Rating

<VueStarRate v-model="rating" :clearable="true" />

RTL Layout

<VueStarRate v-model="rating" :rtl="true" />

Icon Providers

<!-- Lucide icons (requires lucide-vue-next) -->
<VueStarRate v-model="rating" icon-provider="lucide" />

<!-- FontAwesome (requires @fortawesome/fontawesome-free CSS) -->
<VueStarRate v-model="rating" icon-provider="fontawesome" />

<!-- Custom slot icon -->
<VueStarRate v-model="rating" icon-provider="custom">
  <template #icon="{ filled, size, color }">
    <svg :width="size.width" :height="size.height" viewBox="0 0 24 24">
      <polygon points="12,2 15,9 22,9 17,14 19,21 12,17 5,21 7,14 2,9 9,9"
               :fill="filled ? color : 'none'" :stroke="color" stroke-width="2" />
    </svg>
  </template>
</VueStarRate>

Custom Star Count

<VueStarRate v-model="rating" :max-stars="10" />

Counter & Tooltips

<!-- Show counter -->
<VueStarRate v-model="rating" :show-counter="true" />

<!-- Custom counter template -->
<VueStarRate v-model="rating" :show-counter="true" counter-template="{value} / {max} stars" />

<!-- Tooltips on hover -->
<VueStarRate v-model="rating" :show-tooltip="true" />

<!-- Custom tooltip labels -->
<VueStarRate
  v-model="rating"
  :show-tooltip="true"
  :tooltip-labels="['Terrible', 'Bad', 'OK', 'Good', 'Excellent']"
/>

Full Configuration

<VueStarRate
  v-model="rating"
  :max-stars="5"
  :allow-half="true"
  :readonly="false"
  :show-counter="true"
  :show-tooltip="true"
  size="lg"
  :colors="{
    empty: '#27272a',
    filled: '#fbbf24',
    hover: '#fcd34d',
    half: '#fbbf24',
  }"
  :animation="{
    enabled: true,
    duration: 200,
    type: 'scale',
  }"
  @change="(val, old) => console.log(val, old)"
  @hover="(val) => console.log('hover:', val)"
/>

📋 Props API

| Prop | Type | Default | Description | | ------------------ | ------------------------------------------ | --------------------- | ---------------------------------------- | | v-model | number | 0 | Rating value | | maxStars | number | 5 | Maximum number of stars | | allowHalf | boolean | false | Enable half-star ratings | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Size preset | | iconSize | number \| { width, height } | auto | Custom pixel size | | iconProvider | 'custom' \| 'lucide' \| 'fontawesome' | 'custom' | Icon renderer | | colors | Partial<StarColors> | see below | Color configuration | | animation | Partial<AnimationConfig> | see below | Animation configuration | | readonly | boolean | false | Disable user interaction | | disabled | boolean | false | Disable + grey out component | | clearable | boolean | false | Show a clear button when rating > 0 | | allowReset | boolean | true | Click active star again to reset | | showCounter | boolean | false | Show rating counter | | counterTemplate | string | '{value} / {max}' | Counter format template | | showTooltip | boolean | false | Show tooltips on star hover | | tooltipLabels | string[] | — | Custom tooltip labels per star | | minRating | number | 0 | Minimum selectable value | | step | number | 1 | Increment step (overridden by allowHalf) | | rtl | boolean | false | Right-to-left layout | | inline | boolean | false | Inline layout mode | | gap | number | 4 | Gap between stars in pixels | | ariaLabel | string | 'Star rating' | Accessible group label | | className | string | — | Extra CSS class on root element | | faIcons | { empty?, filled?, half? } | — | FontAwesome class overrides | | customIcon | CustomIconRenderer | — | Programmatic icon render function |

StarColors type

interface StarColors {
  empty:   string  // default '#d1d5db' — unfilled star
  filled:  string  // default '#fbbf24' — filled star
  hover:   string  // default '#f59e0b' — hovered star
  half?:   string  // default = filled  — half-filled star
}

AnimationConfig type

interface AnimationConfig {
  enabled:  boolean                               // default true
  duration: number                                // default 200 ms
  type:     'scale' | 'bounce' | 'pulse' | 'none' // default 'scale'
}

🎰 Slots

| Slot | Scoped props | Description | | --------- | -------------------------------------- | --------------------------- | | icon | { filled, half, size, color, index } | Custom icon per star | | counter | { value, max } | Custom counter content | | clear | — | Custom clear button content |

📡 Events

| Event | Payload | Description | | -------- | ------------------- | ---------------------------------- | | change | (value, oldValue) | Rating changed by user interaction | | hover | number \| null | Hover enters / leaves a star | | focus | — | Component received keyboard focus | | blur | — | Component lost focus |

update:modelValue is handled automatically by v-model / defineModel.

⌨️ Keyboard Navigation

| Key | Action | | ------- | ---------------------- | | → ↑ | Increase rating | | ← ↓ | Decrease rating | | Home | Set to minimum | | End | Set to maximum | | 1-9 | Jump to specific value | | 0 | Reset to minimum |

🖥️ Exposed Methods

const ratingRef = ref<InstanceType<typeof VueStarRate>>();

ratingRef.value?.reset();          // Reset to initial value
ratingRef.value?.setRating(3.5);   // Set programmatically
ratingRef.value?.getRating();      // Get current value
ratingRef.value?.focus();          // Focus the component
ratingRef.value?.blur();           // Blur the component

🔄 Migrating from v2 to v3

Breaking Changes

| v2.x | v3.x | | --------------------------------- | --------------------------------------------------------- | | modelValue prop | Managed by defineModel — template syntax unchanged | | lucideIcons prop | Removed — use icon-provider="lucide" instead | | role="slider" on container | role="group" — WCAG 2.2 compliant | | animation: { scale: 1.15 } | animation: { type: 'scale' } — no numeric scale key | | peerDependencies: vue ^3.3.0 | peerDependencies: vue ^3.5.0 | | Options API data()/methods | Composition API + <script setup> / defineModel |

Animation Migration

<!-- v2 — scale was never a valid AnimationConfig key -->
:animation="{ enabled: true, duration: 200, scale: 1.15 }"

<!-- v3 — use type instead -->
:animation="{ enabled: true, duration: 200, type: 'scale' }"

📦 Bundle size & optional peers

vue-js-star-rating is zero-dependency at the package boundary. The default SVG icon ships inside the main bundle; Lucide and FontAwesome icon providers are loaded lazily via defineAsyncComponent, so their optional peers are only required — and only fetched at runtime — when you actually render them.

| What you import | What's pulled into your bundle | | --- | --- | | import { VueStarRate } from 'vue-js-star-rating' + default icon | Component + SVG star only (~3 KB gzipped) | | <VueStarRate icon-provider="lucide" /> | Above + a separate LucideIcon-[hash].js chunk + lucide-vue-next | | <VueStarRate icon-provider="fontawesome" /> | Above + a separate FontAwesomeIcon-[hash].js chunk | | <VueStarRate icon-provider="custom"><template #icon /></VueStarRate> | Component only — you supply the markup |

If you choose a non-Lucide provider, you do not need to install lucide-vue-next — the consumer bundler will not try to resolve it at build time. (Issue #7 regression test ships in tests/lazyIcons.spec.ts.)

# Only when you set icon-provider="lucide"
pnpm add lucide-vue-next

# Only when you set icon-provider="fontawesome"
# (the CSS classes the wrapper emits ship with the free pack)
pnpm add @fortawesome/fontawesome-free

❓ FAQ

Do I need lucide-vue-next if I use FontAwesome (or my own icon)?

No. Since v3.1.0, icon providers are loaded with defineAsyncComponent. The static dependency graph from import { VueStarRate } from 'vue-js-star-rating' does not include lucide-vue-next, so consumer bundlers (Vite, Webpack, Rollup, esbuild) will not require it to be installed.

Is it SSR-safe? Does it work with Nuxt 3?

Yes. The component renders deterministically on the server. Async icon providers resolve on the client after hydration — wrap your usage in <ClientOnly> (Nuxt) or <Suspense> if you need the icon present in the initial HTML, otherwise the default SVG provider works fully server-side.

What is the bundle size?

About 3 KB gzipped for the default SVG path (component + composable + types stripped). Lucide and FontAwesome chunks are emitted as separate files and only fetched when the matching provider is rendered.

Is it accessible?

The root carries role="group" + aria-label. Each star button exposes aria-pressed. The counter uses aria-live="polite" for live announcements. Full keyboard navigation: arrow keys, Home, End, 0–9. Animations are gated on prefers-reduced-motion since v3.1.0. Compliant with WCAG 2.2 Level AA.

Can I use it without v-model?

Yes — pass :model-value and listen to @change (or @update:modelValue). The composable useStarRating is also exported if you want headless control.

How do I clear the rating programmatically?

const star = ref<InstanceType<typeof VueStarRate>>();
star.value?.setRating(0); // or star.value?.reset()

⚖️ Comparison

| Feature | vue-js-star-rating | vue-star-rating | vue3-star-ratings | | --- | :---: | :---: | :---: | | Vue 3.5+ (defineModel) | ✅ | — | partial | | TypeScript-first | ✅ | — | partial | | Runtime dependencies | 0 | 1 | 1 | | Tree-shakeable lazy icons | ✅ | — | — | | Half-star precision | ✅ | ✅ | ✅ | | Keyboard navigation | ✅ (full) | partial | partial | | aria-pressed + aria-live | ✅ | — | — | | WCAG 2.2 compliant | ✅ | — | — | | RTL | ✅ | — | — | | prefers-reduced-motion | ✅ | — | — | | Custom icon via slot | ✅ | partial | — | | SSR / Nuxt 3 | ✅ | partial | ✅ |

🛠️ Development

# Clone the repository
git clone https://github.com/pooyagolchian/vue-star-rate.git
cd vue-star-rate

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

# Documentation development
pnpm docs:dev

# Build documentation
pnpm docs:build

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📄 License

MIT © Pooya Golchian