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.

Compatibility

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

License

MIT