jQuery Bar Rating

Minimal, light-weight jQuery ratings.

jQuery Bar Rating Plugin works by transforming a standard select field into a rating widget. The rating widget can be flexibly styled with CSS. Take a look at a few examples.

enable disable

1/10 Rating

Movie Rating

Square Rating

Pill Rating

Reversed Rating

Horizontal Rating

How about star ratings?

The plugin comes with a few flavours of star ratings compatible with popular libraries.

Font Awesome

CSS Stars

Bootstrap

How to use

Get the plugin from GitHub or install with Bower or NPM:


bower install jquery-bar-rating


npm install jquery-bar-rating

Create a select field:


<select id="example">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
</select>

If you would like to use one of the provided themes include the theme in the head section of the page.
```
<link rel="stylesheet" href="fontawesome-stars.css">
```

Include and call the plugin (after jQuery v1.7.2+)


<script src="jquery.barrating.min.js"></script>
<script type="text/javascript">
   $(function() {
      $('#example').barrating({
        theme: 'fontawesome-stars'
      });
   });
</script>

The select field will be wrapped in a div with a `.br-theme-fontawesome-stars` class. For a full list of available options please refer to configuration.

Expected result:


<div class="br-wrapper br-theme-fontawesome-stars">
  <select id="example">
    <option value="1">1</option>
    <option value="2">2</option>
    <option value="3">3</option>
    <option value="4">4</option>
    <option value="5">5</option>
  </select>
  ...rating widget...
</div>

Configuration

theme: ''
Specify a theme.

initialRating: null
Specify initial rating by passing select field's option value. If null, the plugin will try to set the initial rating by finding an option with a `selected` attribute.

showValues: false
If set to true, rating values will be displayed on the bars.

showSelectedRating: true
If set to true, user selected rating will be displayed next to the widget.

reverse: false
If set to true, the ratings will be reversed.

readonly: false
If set to true, the ratings will be read-only.

fastClicks: true
Remove 300ms click delay on touch devices.

hoverState: true
Change state on hover.

silent: false
Supress callbacks when controlling ratings programatically.

wrapperClass: 'br-wrapper'
Specify the name of wrapper div's class.
Deprecated: `wrapperClass` option will be removed, please use `theme` option instead.

Methods

$('select').barrating('show');
Shows the rating widget.

$('select').barrating('set', value);
Sets the value of the rating widget.

$('select').barrating('readonly', state);
Switches the read-only state to true or false.

$('select').barrating('clear');
Clears the rating.

$('select').barrating('destroy');
Destroys the rating widget.

Callbacks

onSelect:function(value, text, event)
Fired when a rating is selected.
Notice: If the rating was set programmatically by using the `set` method event will be null.

onClear:function(value, text)
Fired when a rating is cleared.

onDestroy:function(value, text)
Fired when a rating is destroyed.

FAQ

How do I allow users to select empty ratings?

To allow users to select empty ratings simply include an empty option in your select field:


<select id="example">
  <option value=""></option>
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
</select>

How can I specify text that is displayed on the bars?

The `showValues` plugin setting already makes it easy to display option values directly on the bars. For more control over the text that is displayed on the bars you can define `data-html` attribute on each of the <option> elements that will take precedence over actual option value.


<select id="example">
  <option value="1" data-html="good">1</option>
  <option value="2" data-html="better">2</option>
  <option value="3" data-html="best">3</option>
</select>

How do I use the onSelect callback?

The onSelect callback is fired when a user selects a rating or when the `set` method is called to select a rating programmatically. The optional third argument will give you access to the event object if it's available.


$('#example').barrating('show', {
  theme: 'my-awesome-theme'
  onSelect: function(value, text, event) {
    if (typeof(event) !== 'undefined') {
      // rating was selected by a user
      console.log(event.target);
    } else {
      // rating was selected programmatically
      // by calling `set` method
    }
  }
});

License

Dual licensed under the MIT and GPL licenses:

http://www.opensource.org/licenses/mit-license.php
http://www.gnu.org/licenses/gpl.html

Download

Download it at GitHub:

http://github.com/antennaio/jquery-bar-rating