nuxt-ui-star-rating

The missing star rating component for NuxtUI.

NuxtUI doesn't ship a rating/stars component. This fills that gap — fractional display, interactive v-model, custom icons, NuxtUI color tokens or any HTML color, five sizes, fully Tailwind-customizable.

Features

• Fractional values — renders 3.7 out of 5 stars with pixel-accurate clipping
• Interactive mode — hover + click with v-model support
• Read-only mode — pass a static :value for display
• Custom icons — use any Iconify icon (hearts, fire, thumbs-up…)
• Flexible colors — NuxtUI tokens (primary, warning…), Tailwind classes, or raw HTML/hex colors
• 5 sizes — xs, sm, md, lg, xl
• Accessible — ARIA roles and keyboard navigation (Enter / Space)
• Zero extra dependencies — uses only UIcon from NuxtUI

Requirements

• Nuxt 3 / Nuxt 4
• @nuxt/ui installed and configured
• Heroicons available (included with NuxtUI by default)

Installation

Option A — npm

npm install nuxt-ui-star-rating

Then extend in nuxt.config.ts:

export default defineNuxtConfig({
    extends: ['nuxt-ui-star-rating'],
})

<StarRating> is then auto-imported — no import statement needed.

Option B — Copy the component

Copy components/StarRating.vue directly into your project's components/ folder.

Usage

Read-only (display a rating)

<StarRating :value="3.7" />
<StarRating :value="4.5" :max="5" size="lg" />

Interactive (v-model)

<script setup lang="ts">
const rating = ref(0)
</script>

<template>
    <StarRating v-model="rating" :interactive="true" />
    <p>You rated: {{ rating }} / 5</p>
</template>

Custom icon

Any Iconify icon name works:

<!-- Hearts -->
<StarRating :value="4" icon="heroicons:heart-solid" filledColor="#e11d48" />

<!-- Fire -->
<StarRating :value="3" icon="heroicons:fire-solid" filledColor="warning" />

<!-- Thumbs up -->
<StarRating :value="5" icon="ph:thumbs-up-fill" filledColor="primary" />

Color formats

All three formats are supported for filledColor and emptyColor:

<!-- NuxtUI semantic token -->
<StarRating :value="4" filledColor="warning" emptyColor="neutral" />

<!-- Tailwind class -->
<StarRating :value="4" filledColor="text-rose-500 dark:text-rose-400" />

<!-- Raw HTML / hex / rgb -->
<StarRating :value="4" filledColor="#f59e0b" emptyColor="rgb(200,200,200)" />
<StarRating :value="4" filledColor="gold" emptyColor="lightgray" />

All sizes

<StarRating :value="4" size="xs" />
<StarRating :value="4" size="sm" />
<StarRating :value="4" size="md" />  <!-- default -->
<StarRating :value="4" size="lg" />
<StarRating :value="4" size="xl" />

Props

| Prop | Type | Default | Description | |---|---|---|---| | value | number | 0 | Rating to display (read-only). Supports decimals. | | modelValue | number | 0 | Bound value for v-model (interactive mode). | | max | number | 5 | Maximum number of icons. | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Icon size. | | interactive | boolean | false | Enables click and hover input. | | icon | string | 'heroicons:star-20-solid' | Any Iconify icon name. | | filledColor | string | 'text-yellow-400 dark:text-yellow-500' | NuxtUI token, Tailwind class, or HTML color. | | emptyColor | string | 'text-gray-200 dark:text-gray-600' | NuxtUI token, Tailwind class, or HTML color. | | ariaLabel | string | 'Rating' | Accessible label for the group element. |

Events

| Event | Payload | Description | |---|---|---| | update:modelValue | number | Emitted on star click (interactive mode). |

How fractional rendering works

Each icon is a fixed-size container. An empty icon is always rendered as the background. A filled icon is layered on top and its container is clipped to exactly (fraction * 100)% width. No SVG manipulation or gradients required.

icon i = 4, value = 3.7
  filled clip width = (3.7 - 3) * 100% = 70%

License

MIT © Chahine Brini

Features

• Fractional values — renders 3.7 out of 5 stars with pixel-accurate clipping
• Interactive mode — hover + click with v-model support
• Read-only mode — pass a static :value for display
• 5 sizes — xs, sm, md, lg, xl
• Tailwind-friendly — override colors via class props
• Accessible — ARIA roles and keyboard navigation (Enter / Space)
• Zero extra dependencies — uses only UIcon from NuxtUI (heroicons:star-20-solid)

Requirements

• Nuxt 3 / Nuxt 4
• @nuxt/ui installed and configured
• Heroicons available (included with NuxtUI by default)

Installation

Option A — Nuxt Layer (recommended)

Clone or add the repo as a submodule, then extend it in your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
    extends: [
        'path/to/nuxt-ui-star-rating',
    ],
})

<StarRating> is then auto-imported — no import statement needed.

Option B — Copy the component

Copy components/StarRating.vue directly into your project's components/ folder. It will be auto-imported by Nuxt.

Usage

Read-only (display a rating)

<StarRating :value="3.7" />

<!-- With max stars and size -->
<StarRating :value="4.5" :max="5" size="lg" />

Interactive (v-model)

<script setup lang="ts">
const rating = ref(0)
</script>

<template>
    <StarRating v-model="rating" :interactive="true" />
    <p>You rated: {{ rating }} / 5</p>
</template>

Custom colors

<StarRating
    :value="4"
    filledColor="text-orange-400 dark:text-orange-300"
    emptyColor="text-slate-200 dark:text-slate-700"
/>

All sizes

<StarRating :value="4" size="xs" />
<StarRating :value="4" size="sm" />
<StarRating :value="4" size="md" />  <!-- default -->
<StarRating :value="4" size="lg" />
<StarRating :value="4" size="xl" />

Props

| Prop | Type | Default | Description | |---|---|---|---| | value | number | 0 | Rating to display (read-only mode). Supports decimals. | | modelValue | number | 0 | Bound value for interactive / v-model mode. | | max | number | 5 | Maximum number of stars. | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Star size. | | interactive | boolean | false | Enables click and hover input. | | filledColor | string | 'text-yellow-400 dark:text-yellow-500' | TailwindCSS class for filled stars. | | emptyColor | string | 'text-gray-200 dark:text-gray-600' | TailwindCSS class for empty stars. | | ariaLabel | string | 'Star rating' | Accessible label for the star group. |

Events

| Event | Payload | Description | |---|---|---| | update:modelValue | number | Emitted on star click (interactive mode). |

How fractional rendering works

Each star is a fixed-size container. An empty star is always rendered as the background. A filled star is layered on top and its container is clipped to exactly (fraction * 100)% width. No SVG manipulation or gradients required.

star i = 4, value = 3.7
  filled clip width = (3.7 - 3) * 100% = 70%

License

MIT © Chahine Brini