Bootstrap Star Rating bootstrap-star-rating

Thankful to Krajee!
to get more out of us.

NOTE: The plugins on this site, strive to use a lot of CSS3 and HTML5 features in addition to JQuery. Hence, one may find either CSS3, HTML5 or a mix of both to achieve a plugin's requirements in many implementations.

A simple yet powerful JQuery star rating plugin for Bootstrap which supports advanced features like fractional star fill and RTL input support. Developed with a focus on utlizing pure CSS-3 styling to render the control. The plugin uses Bootstrap markup and styling by default, but it can be overridden with any other CSS markup. View a complete demo.

NOTE

Version 2.0 has been released. Refer change log for new features and details.

  1. Convert any HTML input to a star rating control.

  2. The plugin automatically converts an input to a star rating control if you set its class = rating. All options to the input can be passed as HTML5 data attributes.

  3. You can use the HTML 5 number input for polyfill and the plugin will automatically use the number attributes like min, max, and step. However, number inputs have a problem with decimal values on the Chrome Browser. Read the Browser Support section below.

  4. Involves pure CSS3 styling of the stars. Say goodbye to image sprites or playing with image backgrounds. Offers clean scalable vector icons for consistent display across devices.

  5. Specifically uses Bootstrap 3.x styles & glyphs. Can be combined to work better for Bootstrap styled projects (or input group addons).

  6. Ability to clear values and options for the stars. Control where the clear button element can be shown.

  7. Reset star rating to the initial value when the form is reset.

  8. Ability to control and display caption of the selected stars. Each rated star can have its own caption. Control where the caption element can be shown.

  9. Ability to size the rating control including the stars, caption, and clear button. Five prebuilt size templates are available xl, lg, md, sm, and xs.

  10. Support for RIGHT TO LEFT (RTL) input. Automatically changes star styling for RTL.

  11. Triggers JQuery events for advanced development. Events currently available are rating.change, rating.clear, and rating.reset.

  12. Disabled and readonly input star rating support.

  13. Size of the entire plugin is less than 11KB (about 8KB for the minified JS and 3KB for the minified CSS).

Browser Support

If you are using the HTML5 NUMBER input to initialize the rating, please read this. The number field does not accept decimals in Google Chrome. The input is allowed, but when the user submits the form, they get an error message and are instructed to enter a valid number (whole numbers only). Other browsers like Firefox allow decimals on the number fields. Till this is standardized across browsers, the workaround for this is to use a normal text input, and initialize the rating via javascript.

  1. Latest JQuery

  2. Most modern browsers supporting CSS3, HTML5 inputs, & JQuery. For Internet Explorer, one must use IE versions 9 and above to render the rating.

  3. Bootstrap 3.x is optional and used by default, but can be overridden to use any CSS.

The plugin can be installed automatically or manually using one of these options:

Bower Package Manager

Installation via bower package manager is as simple as running:
$ bower install bootstrap-star-rating

Composer Package Manager

You can install bootstrap star rating via composer package manager. Either run

$ php composer.phar require kartik-v/bootstrap-star-rating "dev-master"

or add:

"kartik-v/bootstrap-star-rating": "dev-master"

to your composer.json file

Manual Install

You can also manually install the plugin easily to your project. Just download the source ZIP or TAR ball and extract the plugin assets (css and js folders) into your project.

Step 1: Load the following assets in your header.

<link href="http://netdna.bootstrapcdn.com/bootstrap/3.1.0/css/bootstrap.min.css" rel="stylesheet">
<link href="path/to/css/star-rating.min.css" media="all" rel="stylesheet" type="text/css" />
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="path/to/js/star-rating.min.js" type="text/javascript"></script>

If you noticed, you need to load the jquery.min.js and bootstrap.min.css in addition to the star-rating.min.css and star-rating.min.js.

Step 2a: Initialize the plugin on your page. For example,

// initialize with defaults
$("#input-id").rating();
 
// with plugin options
$("#input-id").rating(['min'=>1, 'max'=>10, 'step'=>2, 'size'=>'lg']);

The #input-id is the identifier for the input on your page, which is hidden automatically by the plugin.

Step 2b: Alternatively, you can directly set the plugin options to any input, through HTML 5 data attributes to your input field.

<input id="input-id" type="number" class="rating" min=1 max=10 step=2 data-size="lg" data-rtl="true">

Note

The plugin will automatically convert inputs with css class rating to a star rating control.

The plugin supports these following options:

stars

int the number of stars to display. Defaults to 5.

glyphicon

boolean whether to use the glyphicon star symbol. Defaults to true. If set to false, will use the unicode black star symbol.

symbol

string any custom star symbol or unicode character to display. This will override the glyphicon settings above.

min

float the minimum value for the rating input. Defaults to 1.

max

float the maximum value for the rating input. Defaults to 5.

step

float the step to increment the rating when each star is clicked. Defaults to 0.5.

disabled

boolean whether the input is disabled. Defaults to false.

readonly

boolean whether the input is read only. Defaults to false.

rtl

boolean whether the rating input is to be oriented RIGHT TO LEFT. Defaults to false.

showClear

boolean whether the clear button is to be displayed. Defaults to true.

showCaption

boolean whether the rating caption is to be displayed. Defaults to true.

size

string size of the rating control. One of xl, lg, md, sm, or xs. Defaults to md.

defaultCaption

string the default caption text, which will be displayed when no caption is setup for the rating in the starCaptions array. This variable defaults to {rating} Stars, where the variable {rating} will be replaced with the selected star rating.

starCaptions

array | function the caption titles corresponding to each of the star rating selected. Defaults to

{
    0.5: 'Half Star',
    1: 'One Star',
    1.5: 'One & Half Star',
    2: 'Two Stars',
    2.5: 'Two & Half Stars',
    3: 'Three Stars',
    3.5: 'Three & Half Stars',
    4: 'Four Stars',
    4.5: 'Four & Half Stars',
    5: 'Five Stars'
}
This can also be configured as a function that returns a star caption based on a supplied parameter val, where val is the calculated rating. For example:
starCaptions: function(val) {
    if (val < 3) {
        return 'Low: ' + val + ' stars';
    } else {
        return 'High: ' + val + ' stars';
    }
}

starCaptionClasses

array | function the caption css classes corresponding to each of the star rating selected. Defaults to

{
    0.5: 'label label-danger',
    1: 'label label-danger',
    1.5: 'label label-warning',
    2: 'label label-warning',
    2.5: 'label label-info',
    3: 'label label-info',
    3.5: 'label label-primary',
    4: 'label label-primary',
    4.5: 'label label-success',
    5: 'label label-success'
}
This can also be configured as a function that returns a star caption based on a supplied parameter val, where val is the calculated rating. For example:
starCaptionClasses: function(val) {
    if (val == 0) {
       return 'label label-default';
    }
    else if (val < 3) {
        return 'label label-danger';
    } 
    else {
        return 'label label-success';
    }
}

clearButton

string the markup for displaying the clear button. Defaults to <i class="glyphicon glyphicon-minus-sign"></i>.

clearButtonTitle

string the title displayed on clear button hover. Defaults to Clear.

clearButtonBaseClass

string the base CSS class for the clear button. Defaults to clear-rating.

clearButtonActiveClass

string the CSS class for the clear button that will be appended to the base class above when button is hovered/activated. Defaults to clear-rating-active.

clearValue

string the value to clear the input to, when the clear button is clicked. Defaults to 0.

clearCaption

string the caption displayed when clear button is clicked. Defaults to Not Rated.

clearCaptionClass

string the CSS Class to apply to the caption displayed, when clear button is clicked. Defaults to label label-default.

captionElement

string the identifier for the container element selector for displaying the caption. Defaults to a div container with .caption class inside the rating control.

clearElement

string the identifier for the container element selector for displaying the clear button. Defaults to a div container with .clear-rating class inside the rating control.

The plugin supports these events:

rating.change

This event is triggered when the star rating is modified or changed. This event also allows you to access these parameters:

  • value: the selected rating value

  • caption: the caption for the selected rating

Example:

$('#input-id').on('rating.change', function(event, value, caption) {
    console.log(value);
    console.log(caption);
});

rating.clear

This event is triggered when the rating is cleared with the clear button.

Example:

$('#input-id').on('rating.clear', function(event) {
    console.log("rating.clear");
});

rating.reset

This event is triggered when the rating is reset to initial value.

Example:

$('#input-id').on('rating.reset', function(event) {
    console.log("rating.reset");
});

The plugin supports these methods:

update

Update the rating by setting a value via javascript. The method accepts a rating value as a parameter.

$('#input-id').rating('update', 3);

refresh

Use this method to dynamically refresh the rating options via javascript after the plugin has been initialized. The method accepts the plugin options entered as an array.

// Example: Call the method below in rating.change event to disable the rating and
// hide the clear button.
$('#input-id').rating('refresh', {disabled: true; showClear: false; showCaption: true});

reset

Reset the rating to the initial value. For example after a form reset.

$('#input-id').rating('reset');

clear

Clear the rating.

$('#input-id').rating('clear');

The plugin has been implemented as extensions in the following frameworks

Sl.FrameworkExtension SourceDeveloped ByExtension Demo
1.Yii Framework 2.0Yii2 WidgetsKrajee Yii2 Star Rating

Do you know any other framework extension using this plugin which is not listed here? Tell us so that we can consider its inclusion in this list.

bootstrap-star-rating is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.