bootstrap-star-rating
NOTE: Version 3.5.4 has been released. Refer change log for details.
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 the documentation or a complete demo at Krajee JQuery plugins.
Features
- Convert any HTML input to a star rating control.
- 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 HTML5data
attributes. - You can use the HTML 5 number input for polyfill and the plugin will automatically use the number attributes like
min
,max
, andstep
. However, number inputs have a problem with decimal values on the Chrome Browser. Read the Browser Support section below. - 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. Optionally one can use the Unicode character set to override symbols.
- Use any of your favorite font icon frameworks to render your star symbols (for example you can easily use the icons from the FontAwesome library).
- Render and display fractional star ratings. Configure number of stars, min, max, step, and theoretically support any fractional rating.
- Uses Bootstrap 3.x styles & glyphs by default. But this can be overridden with plugin parameters and your own CSS styles.
- Support for RIGHT TO LEFT (RTL) input. Automatically changes star styling for RTL.
- Ability to clear values and options for the stars. Control where the clear button element can be shown.
- Reset star rating to the initial value when the form is reset.
- 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.
- Ability to size the rating control including the stars, caption, and clear button. Five prebuilt size templates are
available
xl
,lg
,md
,sm
, andxs
. - Triggers JQuery events for advanced development. Events currently available are
rating.change
,rating.clear
,rating.reset
,rating.refresh
,rating.hover
, andrating.hoverleave
. - Disabled and readonly input star rating support.
- Change stars and caption on mouse hover (new feature since v3.0.0).
- Change stars and caption on slide and drag for mobile/touch devices (new feature since v3.1.0).
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.
Demo
View the plugin documentation and plugin demos at Krajee JQuery plugins.
Pre-requisites
- Bootstrap 3.x
- Latest JQuery
- Most browsers supporting CSS3 & JQuery.
Installation
Using Bower
You can use the bower
package manager to install. Run:
bower install bootstrap-star-rating
Using Composer
You can use the composer
package manager to install. Either run:
$ php composer.phar require kartik-v/bootstrap-star-rating "@dev"
or add:
"kartik-v/bootstrap-star-rating": "@dev"
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.
Usage
Step 1: Load the following assets in your header.
<link href="http://netdna.bootstrapcdn.com/bootstrap/3.3.1/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
for
the plugin to work with default settings.
Step 2: Setup your input markup to automatically initialize the rating
<input id="input-id" type="number" class="rating" min=0 max=5 step=0.5 data-size="lg" >
Step 3: Initialize the plugin on your page for other input types. For example,
// initialize with defaults
$("#input-id").rating();
// with plugin options
$("#input-id").rating({'size':'lg'});
The #input-id
is the identifier for the input (e.g. type=number
) on your page, which is hidden automatically by the plugin.
Alternatively, you can directly call the plugin options by setting data attributes to your input field.
Documentation
Plugin Options
The plugin supports these following options:
stars
int 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 by default. You can also configure the ratingClass
to set your own icon framework font CSS class to render the symbols.
symbol
string any custom star symbol or unicode character to display. This will override the
glyphicon
settings above.
ratingClass
string the CSS class to be appended to the star rating. This is useful when you wish to render the stars using other third party icon font libraries. For example, to render the symbols using Font Awesome icons, you can set this to rating-fa
. The rating-fa
class is a prebuilt CSS style within this plugin, but you can build similar CSS styles for your other font icons. You need to also set glyphicon
property to false
to ensure the symbols do not conflict with glyphicons.
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 star rating. 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 class 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 min
if not set.
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 the 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 the div
container with .clear-rating
class inside the rating control.
hoverEnabled
boolean whether hover functionality is enabled. This will dynamically change the stars and caption on mouse hover. Defaults to true
.
NOTE: The hover functionality will only work on desktop pointing devices and if the input is not
disabled
orreadonly
. For all hover functionalities in this plugin (including properties below), the rating state will be reverted back to original if the mouse is exited out without clicking.
hoverChangeCaption
boolean control whether the caption should dynamically change on mouse hover. Defaults to true
. Will be applicable only if hoverEnabled
is true
.
hoverChangeStars
boolean control whether the stars should dynamically change on mouse hover. Defaults to true
. Will be applicable only if hoverEnabled
is true
.
hoverOnClear
boolean whether to dynamically clear the rating on hovering the clear button. Defaults to true
. Will be applicable only if hoverEnabled
is true
.
Plugin Events
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 valuecaption
: 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");
});
rating.hover
This event is triggered, when the mouse (pointing input device) is hovered inside a star rating or the clear button. This event also allows you to access these parameters:
value
: the selected rating valuecaption
: the caption for the selected ratingtarget
: the target for the hover - returns whether you hovered on thestars
or theclear
button.
Example:
$('#input-id').on('rating.hover', function(event, value, caption, target) {
console.log(value);
console.log(caption);
console.log(target);
});
rating.hoverleave
This event is triggered, when the mouse (pointing input device) is hovered out of a star rating or the clear button without clicking. This event also allows you to access these parameters:
target
: the target for the hover - returns whether you left hovering on thestars
or theclear
button.
Example:
$('#input-id').on('rating.hoverleave', function(event, target) {
console.log(target);
});
rating.refresh
This event is triggered when the rating is refreshed using the refresh method.
Example:
$('#input-id').on('rating.refresh', function(event) {
console.log("rating.refresh");
});
Plugin Methods
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 object (associative 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.
$('#input-id').rating('reset');
clear
Clear the rating.
$('#input-id').rating('clear');
destroy
Destroys the rating.
$('#input-id').rating('destroy');
create
Creates the rating after destroying any existing rating plugin instance.
// will re-create rating based on initial plugin options
$('#input-id').rating('create');
// any new plugin options if passed will be used instead of initial plugin options
$('#input-id').rating('create', {disabled: true});
License
bootstrap-star-rating is released under the BSD 3-Clause License. See the bundled LICENSE.md
for details.