Vue Star Rating Component

Common errors

• Rating not being set to 0 when clicking outside the star or to the left of the first star.

  cause A 'dead' column of pixels prevented resetting to zero or selecting the lowest increment. This was a known issue (issue #22).
  fix This issue was resolved in `vue-star-rating@1.5.0`. Upgrade to this version or newer for Vue 2 projects.

• Glow effect is always on, even when not intended, particularly prominent on dark backgrounds.

  cause An issue where the `glow` effect was permanently active due to a bug in the component's styling or logic.
  fix This specific glow issue was fixed in `vue-star-rating@2.0.3`. Upgrade to this version or newer for Vue 3 projects.

• Initial rating values are being rounded despite `round-start-rating` being set to `false`, especially with async data.

  cause A bug in versions prior to 1.6.1 caused `round-start-rating` to not correctly apply when the initial rating was loaded asynchronously (issue #36).
  fix Upgrade to `vue-star-rating@1.6.1` or higher for Vue 2 projects to correctly apply `round-start-rating` with async data.

• Styling of the star rating component is incorrect or clashing with other CSS in my application.

  cause Older versions of the component (prior to v1.4.0) used generic CSS class names (`.star-rating`) that could easily conflict with other project styles (issue #12).
  fix Upgrade to `vue-star-rating@1.4.0` or newer for Vue 2 projects. This version introduced specific class names (e.g., `.vue-star-rating`) to avoid clashes. Review and update any custom CSS targeting the old class names.

Warnings

• breaking Version 2.x of `vue-star-rating` is specifically for Vue 3, while version 1.6.x and below are for Vue 2. Installing via `npm install vue-star-rating` defaults to the Vue 2 compatible version. For Vue 3, you MUST install with `npm install vue-star-rating@next`.
  Fix: For Vue 3 projects, use `npm install vue-star-rating@next`. For Vue 2, continue with `npm install vue-star-rating` (or explicitly `vue-star-rating@1`).
• breaking Starting with Vue 3 compatible versions (v2.0.2+), the `rating` argument must now be explicitly passed for the component to function correctly.
  Fix: Ensure the `rating` prop is always passed to the `StarRating` component. When using `v-model`, this is handled automatically.
• breaking Internal CSS class names were changed in v1.4.0 to prevent clashes. Custom CSS targeting old class names will no longer work.
  Fix: Review your custom CSS for `vue-star-rating` and update class selectors according to the new naming conventions if you are targeting internal classes. (e.g., `.star-rating` changed to `.vue-star-rating`).
• gotcha Prior to v2.1.0, enabling the `glow` prop required also explicitly setting a `glow-color`. In v2.1.0+, `glow-color` is optional as it will default if not provided.
  Fix: If using `glow` on versions prior to 2.1.0, always specify a `:glow-color` prop, for example: `:glow-color="'#ffd055'"`.
• gotcha The `round-start-rating` prop, intended to prevent initial rating rounding, had an issue where it would still round when the rating was set asynchronously. This was fixed in v1.6.1.
  Fix: Upgrade to `vue-star-rating@1.6.1` or higher for Vue 2 projects if you are encountering issues with `round-start-rating` and asynchronously loaded initial ratings.
• gotcha The `active-color` and `active-border-color` props can accept an array of color values in v2.1.0+ to color each star individually. If a single string is provided, all stars will share that color.
  Fix: To apply different colors to each star, provide an array of color strings, e.g., `:active-color="['red', 'orange', 'yellow', 'green', 'blue']"`.

Install

• npm install vue-star-rating npm
• yarn add vue-star-rating yarn
• pnpm add vue-star-rating pnpm

Imports

• StarRating
  wrong:

  import { StarRating } from 'vue-star-rating';

  correct:

  import StarRating from 'vue-star-rating';

  The component is exported as a default export.
• StarRating (Vue 3)

  import StarRating from 'vue-star-rating';

  For Vue 3, ensure you install `vue-star-rating@next`. The import path remains the same.
• StarRating (CommonJS Vue 2)

  const StarRating = require('vue-star-rating');

  This pattern is typically used in Vue 2 projects or older Node.js environments. For Vue 3, ESM imports are preferred.

Quickstart

This quickstart demonstrates basic usage of `vue-star-rating` with Vue 3, showcasing v-model binding for an interactive rating and a read-only display. It includes several common props like `star-size`, `increment`, `glow`, and `active-color`.

import { createApp, ref } from 'vue';
import StarRating from 'vue-star-rating';

const app = createApp({
  components: {
    StarRating
  },
  setup() {
    const currentRating = ref(3.5);
    const readOnlyRating = ref(4.2);

    const setRating = (rating) => {
      currentRating.value = rating;
      console.log('New rating:', rating);
    };

    return {
      currentRating,
      readOnlyRating,
      setRating
    };
  },
  template: `
    <div>
      <h1>Interactive Star Rating</h1>
      <star-rating
        v-model:rating="currentRating"
        :increment="0.5"
        :star-size="30"
        :show-rating="false"
        :glow="5"
        glow-color="#ffd055"
        active-color="#FFD700"
        inactive-color="#D8D8D8"
        border-color="#ccc"
        :border-width="2"
        :rounded-corners="true"
        :padding="5"
        @update:rating="setRating"
      ></star-rating>
      <p>Your current rating: {{ currentRating }}</p>

      <h2>Read-only Rating</h2>
      <star-rating
        :rating="readOnlyRating"
        :read-only="true"
        :increment="0.01"
        :star-size="25"
        :fixed-points="2"
        :show-rating="true"
        active-color="#42b883"
        inactive-color="#f0f0f0"
      ></star-rating>
      <p>Average rating: {{ readOnlyRating }}</p>
    </div>
  `
});

app.mount('#app');