+ +
+ npm version + MIT License +
+ +
+

Demo

+
+ +
+ + + + + + + + + + +
+ +
+ +
+ +
+ +
+ +
+ +
+
+ + +
+
+
+ +
+

Installation

+ 

npm i star-rating.js

+
+ +
+

Usage

+

Your SELECT option fields must have numerical values.

+ 

<link href="css/star-rating.css" rel="stylesheet">
+
+<select class="star-rating">
+    <option value="">Select a rating</option>
+    <option value="5">Excellent</option>
+    <option value="4">Very Good</option>
+    <option value="3">Average</option>
+    <option value="2">Poor</option>
+    <option value="1">Terrible</option>
+</select>
+
+<script src="js/star-rating.js"></script>
+<script>
+    var stars = new StarRating('.star-rating');
+</script>

+

To rebuild all star rating controls (e.g. after form fields have changed with ajax):

+ 

stars.rebuild();

+

To fully remove all star rating controls, including all attached Event Listeners:

+ 

stars.destroy();

+
+ +
+

Options

+

These are the default options:

+ 

{
+    classNames: {
+        active: "gl-active",
+        base: "gl-star-rating",
+        selected: "gl-selected",
+    },
+    clearable: true,
+    maxStars: 10,
+    stars: null,
+    tooltip: 'Select a Rating',
+}

+

className.active

+
+

Type: String

+

The classname to use for the active (hovered or value <= of the selected value) state of a star.

+
+

className.base

+
+

Type: String

+

The classname to use for the base element that wraps the star rating.

+
+

className.selected

+
+

Type: String

+

The classname to use for the selected state of a star.

+
+

clearable

+
+

Type: Boolean

+

Whether or not the star rating can be cleared by clicking on an already selected star.

+
+

maxStars

+
+

Type: Integer

+

The maximum number of stars allowed in a star rating.

+
+

prebuilt

+
+

Type: Boolean

+

If this option is true, only the event listeners will be added and no DOM manipulation will take place. You will need to ensure that the DOM looks something like this:

+ 

<span class="gl-star-rating">
+    <select>
+        <option value="">Select a rating</option>
+        <option value="5">5 Stars</option>
+        <option value="4">4 Stars</option>
+        <option value="3">3 Stars</option>
+        <option value="2">2 Stars</option>
+        <option value="1">1 Star</option>
+    </select>
+    <span class="gl-star-rating--stars">
+        <span data-value="1"></span>
+        <span data-value="2"></span>
+        <span data-value="3"></span>
+        <span data-value="4"></span>
+        <span data-value="5"></span>
+    </span>
+</span>
+

+
+

stars

+
+

Type: Function

+

This can be used to add a SVG image to each star value instead of using the background images in the CSS.

+
+

tooltip

+
+

Type: String|False

+

The placeholder text for the rating tooltip, or false to disable the tooltip.

+
+
+ +
+

Build

+ 

npm run build

+

The compiled files will be saved in the dist/ folder.

+

Note: If importing this into your project, you will need to add @babel/plugin-proposal-optional-chaining to your babel config.

+

Style Customization

+

Following are the default CSS variable values for Star Rating:

+ 
:root {
+    --gl-star-color: #fdd835;                     /* if using SVG images */
+    --gl-star-color-inactive: #dcdce6;            /* if using SVG images */
+    --gl-star-empty: url(../img/star-empty.svg);  /* if using background images */
+    --gl-star-full: url(../img/star-full.svg);    /* if using background images */
+    --gl-star-size: 24px;
+    --gl-tooltip-border-radius: 4px;
+    --gl-tooltip-font-size: 0.875rem;
+    --gl-tooltip-font-weight: 400;
+    --gl-tooltip-line-height: 1;
+    --gl-tooltip-margin: 12px;
+    --gl-tooltip-padding: .5em 1em;
+    --gl-tooltip-size: 6px;
+}
+

To override any values with your own, simply import the CSS file into your project, then enter new CSS variable values after the import.

+ 

@import 'star-rating';
+
+:root {
+    --gl-star-size: 32px;
+}

+

How to change CSS style priority

+

Sometimes an existing stylesheet rules will override the default CSS styles for Star Ratings. To solve this problem, you can use the postcss-selector-namespace plugin in your PostCSS build on the CSS file before combining with your main stylesheet. This namespace value should be a high priority/specificity property such as an id attribute or similar.

+
+ +
+

Tips

+
    +
  1. If your star rating has a label field, add the pointer-events: none; style to it to prevent the focus event from triggering on touch devices.
    2. +
+
+ +
+

Compatibility

+
    +
  • All modern browsers
    • +
+

If you need to use the Star Rating library in a unsupported browser (i.e. Internet Explorer), use the Polyfill service. +

+ +
+

License

+

MIT

+
+ +