Your generous donation allows me to continue developing and updating my code!
Star Rating widget
  • Overview
  • API 1
  • API 2
  • Demos
  • Download & Support
  • Background
  • License

What is this?

The Star Rating widget is a plugin for the jQuery javascript library that creates a non-obstrusive star rating control based on a set of radio buttons or select option.

What it does?

  • It turns a collection of radio boxes / select options into a neat star-rating control.
  • It creates the interface based on standard form elements, which means the basic functionality will still be available even if Javascript is disabled.
  • It gives you the full access to each instance of "stars" created on the page, with an easy to use syntax provided by the jQuery UI core library. See Examples tab for more info.

Quick example with RADIO boxes:

Before:
After: Very good
0
1
2
3
4
5
6
7
8
9
10

Quick example with SELECT options:

Before:
After: Not that bad
1
2
3
4
5

Sample markup:

All examples here contains the markup shown below. The wrapper is used as a scope in Stars() constructor to extract all the radio buttons (select options) and remain it's name and value as a hidden input. Note that all other elements from the wrapper will stay intact.

view plainprint?
  1. <form>
  2.     Rating: <span id="stars-cap"></span>
  3.     <div id="stars-wrapper1">
  4.         <input type="radio" name="newrate" value="1" title="Very poor" />
  5.         <input type="radio" name="newrate" value="2" title="Poor" />
  6.         <input type="radio" name="newrate" value="3" title="Not that bad" />
  7.         <input type="radio" name="newrate" value="4" title="Fair" />
  8.         <input type="radio" name="newrate" value="5" title="Average" checked="checked" />
  9.         <input type="radio" name="newrate" value="6" title="Almost good" />
  10.         <input type="radio" name="newrate" value="7" title="Good" />
  11.         <input type="radio" name="newrate" value="8" title="Very good" />
  12.         <input type="radio" name="newrate" value="9" title="Excellent" />
  13.         <input type="radio" name="newrate" value="10" title="Perfect" />
  14.     </div>
  15. </form>

- or -

view plainprint?
  1. <form>
  2.     Rating: <span id="stars-cap"></span>
  3.     <div id="stars-wrapper2">
  4.         <select name="selrate">
  5.             <option value="1">Very poor</option>
  6.             <option value="2">Not that bad</option>
  7.             <option value="3">Average</option>
  8.             <option value="4" selected="selected">Good</option>
  9.             <option value="5">Perfect</option>
  10.         </select>
  11.     </div>
  12. </form>

Usage:

Turning RADIO buttons into star rating type:

view plainprint?
  1. $("#stars-wrapper1").stars();
0
1
2
3
4
5
6
7
8
9
10

Turning SELECT box into star rating type:

view plainprint?
  1. $("#stars-wrapper2").stars({
  2.     inputType: "select"
  3. });
0
1
2
3
4
5

Disabe Stars. Note, it's also possible to pass disabled="disabled" parameter through HTML code instead!

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     disabled: true
  3. });
1
2
3
4
5
6
7
8
9
10

Adding an "onHover" caption element:

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     captionEl: $("#stars-cap")
  3. });
Rating: Average
0
1
2
3
4
5
6
7
8
9
10

Split Stars:

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     split: 2
  3. });
0
1
2
3
4
5
6
7
8
9
10

Only one vote, please!

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     oneVoteOnly: true
  3. });
1
2
3
4
5
6
7
8
9
10

Select the Stars by ID or Value. Note, to remove selection use "-1" for ID or "cancelValue" for Value

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     cancelValue: 99 // PS. Omit this line if your cancelValue is 0 (default)
  3. });
  4.  
  5. // and later...
  6. $("#stars-wrapper1").stars("selectID", -1); // remove selection
  7. $("#stars-wrapper1").stars("selectID", 0); // select first Star
  8. $("#stars-wrapper1").stars("select", 99); // remove selection
  9. $("#stars-wrapper1").stars("select", 1); // select first Star (see element Value in HTML source)
  10.     
1
2
3
4
5
6
7
8
9
10

Enter value:

Callback:

I think this is the most common example, where you have two Star controls. The first one represents an Average rating and is disabled by default, while the second one is enabled, allowing the user to vote for an item.
In this example I will simply pass the selected value from right to left control, although in "real life", you will have to submit selected value to the server and then use returned data to set the Stars accordingly.
The callback is fired each time an element is clicked and it has three arguments: Stars instance, string representing clicked element ("star" or "cancel") and the Value assigned to the clicked element.

Average: Good  
1
2
3
4
5
6
7
8
9
10
Rating:
0
1
2
3
4
5
6
7
8
9
10
view plainprint?
  1. $("#stars-wrapper2").stars({ // already disabled via markup
  2.     inputType: "select",
  3.     split: 2,
  4.     captionEl: $("#stars-wrapper2-cap")
  5. });
  6. $("#stars-wrapper1").stars({
  7.     split: 2,
  8.     captionEl: $("#stars-wrapper1-cap"),
  9.     callback: function(ui, type, value){
  10.         $("#stars-wrapper2").stars("select", value);
  11.         $("#stars-wrapper2-red").html(value==ui.options.cancelValue ? "Rating removed" : "Rating saved! ("+value+")").stop().css("opacity", 1).fadeIn(30);
  12.         setTimeout(function(){ $("#stars-wrapper2-red").fadeOut(1000) }, 2000);
  13.     }
  14. });

More precise "Average" display:

I've been pointed correctly that in previous example, the "Average rating" is rounded to the number of INPUTs only. Frankly speaking, it wasn't my intention to add support for "Average rating" in this widget, although I will show you yet another way how to obtain such functionality. This technique is based on two, overlaping DIVs.

NOTE: I removed all the useless stuff from this example - just to show you the rough idea, so it may work a little bit different from what you can see on this page. Also, the rating counter will automatically reset after 20 votes.

Average: 7.80 (5) 5665
Rating:
1
2
3
4
5
6
7
8
9
10
view plainprint?
  1. <!-- example CSS declarations -->
  2. <style type="text/css">
  3. .stars-off, .stars-on {
  4.     position: relative;
  5.     height: 16px;
  6.     background: url(jquery.ui.stars.gif) repeat-x 0 -32px;
  7. }
  8.  
  9. .stars-on {
  10.     position: absolute;
  11.     background-position: 0 -48px;
  12. }
  13. </style>
  14.  
  15. <!-- example DOM -->
  16. Average: <span id="fake-stars-cap"></span>
  17. <div id="fake-stars-off" class="stars-off" style="width:160px"><div id="fake-stars-on" class="stars-on"></div></div>

view plainprint?
  1. $("#stars-wrapper1").stars({
  2.     cancelShow: false,
  3.     captionEl: $("#stars-cap"),
  4.     callback: function(ui, type, value)
  5.     {
  6.         $.getJSON("ratings.php", {rate: value}, function(json)
  7.         {
  8.             $("#fake-stars-on").width(Math.round( $("#fake-stars-off").width() / ui.options.items * parseFloat(json.avg) ));
  9.             $("#fake-stars-cap").text(json.avg + " (" + json.votes + ")");
  10.         });
  11.     }
  12. });

How to retrieve Stars instance (outside of callback function):

Let's say you can't use the callback function, but still need to access the particular Stars instance.
The answer is the jQuery's internal $.data() function.

view plainprint?
  1. $("#stars-wrapper1").stars();
  2.  
  3. // Retrieve instance
  4. var ui = $("#stars-wrapper1").data("stars");
  5. // Read options
  6. var currID    = ui.options.checked; // Get current ID
  7. var currValue = ui.options.value; // Get current Value
  8. var currTitle = ui.options.title; // Get current Title
  9. var cancValue = ui.options.cancelValue; // Get Cancel value
  10. // Remove Cancel button
  11. ui.$cancel.remove();
  12.     
Rate: Average
0
1
2
3
4
5
6
7
8
9
10





view plainprint?
  1. // PS. The instance can be also retreived at creation time:
  2. var ui = $("#stars-wrapper1").stars();
Version: 3.0.1
jQuery
jQuery UI
jQuery
user interface

Changelog

  • v 3.0 (Apr 20, 2010)
    • added support for jQuery 1.4.2 and jQuery UI 1.8
      Thanks again for all your kind emails :)
    • files renamed to follow UI naming convention
  • v 2.1 (Jun 9, 2009)
    • added Event parameter to callback function
    • integration of a "Not Applicable" field
    • added support for FORM Reset event
  • v 2.0 (May 5, 2009)
    • added support for jQuery 1.3.2 and jQuery UI 1.7.1
  • v 1.1 (Aug 8, 2008)
    • fixed initialization of hidden input value
  • v 1.0 (Jul 17, 2008)
    • first public release

Contact / Find me

  • Email: orkans@gmail.com
  • Twitter: orkans
  • DeviantART: orkanorkan

Advertisements

$(function(){
© Orkan 2008-2010.
$LastChangedDate:: 2010-05-01 #$
$Revision: 165 $
});
Hosting provided by Byet Internet
Bookmark and Share
^^ Top valid CSS? valid HTML?