npm version MIT License

For production, use the files from the dist/ folder.

Demo

Installation

Use one of the following methods to add the Star Rating library to your project:

Usage

Load the dist/star-rating.css and dist/star-rating.min.js files somewhere on your page and then trigger the Star Ratie Star Rating library as follows:

var starRatingControls = new StarRating( '.star-rating' );

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

starRatingControls.rebuild();

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

starRatingControls.destroy();

HTML markup

Your SELECT option fields must have numerical values.

<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>

Options

Default options

{
    classname: "gl-star-rating",
    clearable: true,
    initialText: "Select a Rating",
    maxStars: 10,
    showText: true,
}

classname

Type: String

Determines the classname to use of the rendered star-rating HTMLElement. If you change this, make sure you also change the SCSS $star-rating[base-classname] map variable to match.

clearable

Type: Boolean

Determines whether the star rating can be cleared by clicking on an already pre-selected star.

initialText

Type: String

Determines the initial text when no value is selected. This has no effect if `showText` is set to false.

maxStars

Type: Integer

Determines the maximum number of stars allowed in a star rating.

showText

Type: Boolean

Determines whether or not the rating text is shown.

Build

star-rating.js uses npm or yarn to manage package dependencies and gulp to build from src/.

$ yarn
$ gulp

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

Style Customization

Sass is used to build the stylesheet so you can @import the src/star-rating.scss file to compile it directly into your Sass project.

Following are the default sass values for Star Rating, they are contained in a map variable.

$star-rating-defaults: (
    base-classname : 'gl-star-rating',
    base-display   : block,
    base-height    : 26px,
    font-size      : 0.8em,
    font-weight    : 600,
    parent         : '',
    star-empty     : url(../img/star-empty.svg),
    star-full      : url(../img/star-full.svg),
    star-half      : url(../img/star-half.svg),
    star-size      : 24px,
    text-background: #1a1a1a,
    text-color     : #fff,
);

To override any values with your own, simply create a new $star-rating map variable and include only the values you wish to change.

Important: Make sure you define $star-rating before you import the src/star-rating.scss file:

$star-rating: (
    base-height: 32px,
    star-size  : 30px,
);
@import "../../node_modules/star-rating.js/src/star-rating"

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 specify a "parent" option in the $star-rating map variable. This option value should be a high priority/specificity property such as an id attribute or similar.

In the following example, all Star Rating css rules will begin with [id^=stars] which targets any id attributes that begin with "stars" (i.e. #stars-1):

$star-rating: (
    parent: '[id^=stars]',
);

The CSS rule .gl-star-rating { ... } now becomes [id^=stars] .gl-star-rating { ... }.

Compatibility

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

License

MIT