How to Build a Star Ratings jQuery Plugin

Lately I've been working with jQuery plugins and I decided to create a tutorial demonstrating how to use the jQuery plugin system to build a simple star ratings control.

Almost all controls and features within jQuery are now built using the plugin architecture. It's actually a very simple system, and jQuery provides some pretty good documentation to get you started. Like always, let's start with an example of what we're going to build. Below I've got two star ratings controls with differing amounts of stars - one with 10 and one with 5.

Here's the source code required to build this example.

Just like any other jQuery control, all that's needed is an empty div to hold it. Here I've created two - one for the 10 star example, and one for the 5 star example. In the head of the document, we have to include all of our needed files: the CSS file that describes the look of our stars, jQuery itself, the ratings plugin, and the script that actually tells the plugin to create the controls.

Let's start with example.js.

If you've worked with any jQuery UI controls, this should look pretty familiar. We first get a jQuery object for our example div and call ratings(), which will populate the div with the ratings control. Whatever number is passed into ratings will be used to set the number of stars. You can also pass a second parameter that sets the initial rating to something other than zero. We then bind to the 'ratingchanged' event and set the contents of our "Your Rating" label to the selected rating. And that's all that's required to create the ratings controls.

Next up is the CSS. This will be pretty important if you want your ratings control to look different than mine.

jquery-ratings-star is used to set the look and feel for all stars. position and float should not be changed or the stars will be put in strange places, but everything else can be tweaked to get your desired look. jquery-ratings-full is simply used to set the look of the star when it is highlighted.

All right, now down to the meat of the plugin, jquery.ratings.js. The very first thing we need to do is tell jQuery about the new function, ratings.

This function satisfies the bare minimum requirements for a new jQuery function. All new public functions are added to the jQuery.fn object. All new functions must return the jQuery object, unless otherwise stated. The function should also end with a semi-colon to prevent compression from breaking the code.

Unfortunately, this empty function doesn't do us any good. We need to actually start building some stuff. We'll be using the this object passed into the function in order to add our ratings control. Since this could be a selector containing more than one element, we need to iterate over it using each.

The first thing I do is save this into a local variable. Because of some scoping issues later, this won't always refer to the jQuery object. Next up, I set up an each to loop through each element in the selector. Since each returns the jQuery object, I can simply return it from my function.

Next up we need to set up the container div that's going to hold our stars.

Before I do anything, I make sure initialRating is initialized to something. If the user did not pass in a value, it will be set to 0. I then save the container element and a jQuery object for the container element to variables. Next, I create an array to hold all of my star objects. I then create and set a field on the container element to hold the selected rating. Lastly, I set overflow to auto so the container div will expand to hold the child objects.

We've finally made it to the point where we can build the stars.

Here we have a simple loop to create stars based on the number passed in by the user. First up, I actually need an element to hold the star, so I create one using document.createElement. I then get a jQuery object from the new element. Next, I set the rating that this star represents and add the jquery-ratings-star css class. If the star is beneath the specified initial rating, I add the jquery-ratings-full class to it to make it highlighted. All that's left is to add it as a child to the container and push it into the stars array.

If you were to run the code right now, you'd see a bunch of gray stars. Let's hook up the events to actually make it work.

This is actually the complete code. We've now added all the events that are required to add interactivity to the ratings control. The first event is hooked to each star's click. Whenever a star is clicked, the container's rating is updated and the 'ratingchanged' event is triggered. The next event, mouseenter, makes sure the correct stars are highlighted. Whenever a star is moused over, all stars beneath is are highlighted and all stars greater than it are unhighlighted. The last event is hooked to the container. This event makes sure the correct number of stars are highlighted when the user's mouse leaves the control. The highlighted stars should revert back to the last selected state when the mouse leaves. This is done similar to the star's mouse enter event. Every star beneath the current rating is highlighted and every star above the current rating is unhighlighted.

And that's it. Now we've got a working jQuery plugin for star ratings. If you've comments, questions, or suggested feature additions to this control, leave them below or in the forums.