star-rating.js

A zero-dependency library that transforms a select with numerical-range values (i.e. 1-5) into a dynamic star rating element.

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

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

Here 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',
}

classNames.active

Type: String

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

classNames.base

Type: String

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

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

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

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.

Contributing

All changes should be committed to the files in src/.

Changelog

v4.0.5 - [2021-02-03]

• Fixed an invalid change event from being triggered by the reset event

v4.0.4 - [2021-02-02]

• Export a babel-transpiled commonjs module

v4.0.3 - [2021-01-29]

• Fixed rollup config to support optional-chaining in babel

v4.0.2 - [2021-01-23]

• Fixed compatibility mode (when 'function' !== typeof options.stars)
• Removed trigger of change event after init as this could trigger unwanted validation

v4.0.1 - [2021-01-22]

• Fixed the change event for disabled SELECT elements

v4.0.0 - [2021-01-22]

• Code has been rewritten as an ES6 module and optimised
• Added requestAnimationFrame to the pointer move events
• Added the stars option which allows you to use custom SVG images for each star
• Replaced the classname option with the classNames option
• Replaced the initialText with the tooltip option
• Replaced gulp with rollup for the build
• Replaced SASS with PostCSS

v3.4.0 - [2020-10-18]

• Specify passive:false on event listeners to suppress Chrome warnings

v3.2.0 - [2020-07-13]

• Cleanup stale DOM if needed before initializing

v3.1.8 - [2020-06-29]

• Fixed clearable option
• Fixed events on disabled SELECT

v3.1.5 - [2019-11-01]

• Added ability to use a NodeList as a selector

v3.1.4 - [2019-01-28]

• Updated package URL

v3.1.3 - [2019-01-27]

• Fixed issue when used outside of a FORM

v3.1.2 - [2019-01-07]

• Fixed issue that allowed multiple star-rating transformations on the same SELECT element

v3.1.1 - [2018-07-27]

• Provided an un-minified CSS file in /dist
• Removed the change event trigger from the reset event

v3.1.0 - [2018-07-24]

• Changed the star-filled SCSS map option to star-full
• Changed the star-empty, star-full, and star-half SCSS map options to url(...). This allows one to use none as the value of background-image.

v3.0.0 - [2018-07-24]

• Dropped support for Internet Explorer (use polyfill.io, specifically: Element.prototype.closest, Element.prototype.dataset, Event)
• Removed the onClick option (listen for the change event instead)

v2.3.1 - [2018-07-22]

• CSS improvements

v2.3.0 - [2018-07-20]

• Added a $star-rating[parent] SCSS option

v2.2.2 - [2018-07-16]

• Fixed IE 11+ compatibility

v2.2.1 - [2018-07-13]

• Fixed touch events on Android devices

v2.2.0 - [2018-07-09]

• Added a classname option
• Added a $star-rating[base-classname] SCSS option
• Added touch events
• Fixed detection of an unset option value
• Optimised the minified output
• Removed unused code

v2.1.1 - [2018-05-25]

• Fixed jshint warnings

v2.1.0 - [2018-05-11]

• Added support for the keyboard
• Fixed accessibility support
• Fixed RTL support

v2.0.0 - [2018-05-02]

• Major rewrite of library
• Added support for loading as a module
• Added support for RTL
• Removed jQuery plugin
• Removed IE9 support

v1.3.3 - [2017-04-11]

• Fixed race conditions preventing correct element.outerWidth calculation

v1.3.1 - [2016-12-22]

• Fixed checking existence of parent form element before attaching an event to it
• Fixed mousemove event not correctly unattaching

v1.3.0 - [2016-10-10]

• Changed clickFn to onClick which now passes the select HTMLElement as the argument

v1.2.2 - [2016-10-10]

• Fixed "reset" event when the clearable option is false

v1.2.1 - [2016-10-09]

• Fixed resetting the star-rating when a form "reset" event is triggered

v1.2.0 - [2016-10-09]

• Removed dependencies
• Fixed HTML5 “required” attribute validation

v1.1.0 - [2016-10-06]

• Added showText option

v1.0.1 - [2016-10-06]

• Fixed using the wrong left offset

v1.0.0 - [2016-10-06]

• Initial release

License

MIT