Star Rating jQuery Plugin

*****

Getting Started

1) Download the Plugin

2) Add the Plugin JavaScript File

Include the plugin JavaScript file in your document before you reference the plugin:

<script type="text/javascript" src="jquery.star-rating.js"></script>

You can view the JavaScript file in the repository.

3) Add the CSS and/or Font Files

If you're already using Font Awesome, you don't need to include any additional CSS or font files, only the plugin JavaScript file.

Using the Bundled Font and CSS

This repo comes with a streamlined Font Awesome that includes only the 4 required glyphs. It is syntactically identical to Font Awesome. To use it, add this to the document <head>:

<link rel="stylesheet" href="css/fa-stars.css">

You can view the CSS files in the repository.

If you change the folder where you store the font files, you'll need to update the CSS files accordingly.

If you must support IE7, you can include this as well:

<!--[if lt IE 8]><link rel="stylesheet" href="css/fa-stars-ie7.css"><![endif]-->

Using the Full Font Awesome Framework

If you don't want to use the bundled font described above, you can include the full Font Awesome.

The easiest way to do that is to include this stylesheet from the Bootstrap CDN in the <head> of your document:

<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

Otherwise, check out the Font Awesome documentation for more information.

License

You are free to use this script for commercial and non-commercial projects. I would love to hear from you if you use it or have input.

If you find this dropdown script to be especially useful and can donate some funds, thank you and here is the link to donate:

Why Use Font Glyphs Instead of Images?

In a nutshell, using font glyphs for icons allows you to quickly control things like icon size (fonts glyphs are gracefully scalable vectors) and icon color.

If you really want to, you can use images with this plugin. For example, to change the default star element, update the "star" configuration option to look something like this:

star: $('<img>').attr('src', 'star.png'),

Basic Examples with Default Options

These examples demonstrate different ways to specify a rating and/or a maximum rating, without any additional configuration.

It wouldn't really be possible to determine what the maximum rating is without specifying it. You can do that in your element, as with some of these examples, or during initialization (described later).

Rating: 5.5/10 stars
HTML: <span class="rating">5.5/10 stars</span>

Rating: 1
HTML: <span class="rating">1</span>

Rating: /4
HTML: <span class="rating">/4</span>

Rating:
HTML: <span class="rating"></span>

Rating: 0/6
HTML: <span class="rating">0/6</span>

Rating: ******
HTML: <span class="rating">******</span>

Rating: 0
HTML: <span class="rating">0</span>

Rating: 3.5
HTML: <span class="rating">3.5</span>

Rating: 6.34/7 foo
HTML: <span class="rating">6.34/7 foo</span>

Rating: 4.2 of 5
HTML: <span class="rating">4.2 of 5</span>

Rating: 3.75 out of 5
HTML: <span class="rating">3.75 out of 5</span>

Rating: 2.1 out of 4 stars
HTML: <span class="rating">2.1 out of 4 stars</span>

Rating: 5.75 out of 6 star rating
HTML: <span class="rating">5.75 out of 6 star rating</span>

Rating: 3.75/5
HTML: <span class="rating">3.75/5</span>

JavaScript:
jQuery(function($) {
	$('.rating').star_rating();
});

Global Configuration (e.g. Maximum Rating)

Chances are, you don't have more than one maximum amount of stars for a rating per-site. You can specify a global max rating like this:

Rating: 4.2
HTML: <span class="global-max">4.2</span>

Rating: 6.43
HTML: <span class="global-max">6.43</span>

JavaScript:
jQuery(function($) {
	$.fn.star_rating({
		max: 7
	});

	$('.global-max').star_rating();
});

Note that from here on out, examples will be using this value for the maximum. We've specified an integer for max instead of the default method, so the default method is now overridden.

Specifying an Action When a Star is Clicked

You might want to make something happen when a star is clicked, such as storing a new rating. This plugin can do that. Enabling the click event also exposes a "hover" event, which is given a sensible default.

The plugin includes an example of posting and receiving rating data on a click event, and it is commented out.

Try clicking on a star in this example:

Rating: 5.5
HTML: <span class="click-event">5.5</span>

JavaScript:
jQuery(function($) {
	$('.click-event').star_rating({
		// Add some functionality for when a star is clicked
		click: function(clicked_rating, event) {
			event.preventDefault();

			alert(
				'You clicked on a star rating of ' + clicked_rating +
				(this.max() ? ' out of ' + this.max() : '') + '.\n\n' +
				'We\'ll update the instance now with that rating.'
			);

			this.rating(clicked_rating);
		}
	});
});

Additional Methods

Rating: 5.5/10 stars
HTML: <span class="methods-star-rating">5.5/10 stars</span>

'rating'

This does not update the underlying rating text -- which can be in many formats -- only the rendering. That will of course will not directly affect your keywords one way or the other. If you need it to update the text as well, please file an issue.

$('.methods-star-rating').star_rating('rating', new_rating_value);

'remove'

$('.methods-star-rating').star_rating('remove');

'reload'

$('.methods-star-rating').star_rating('reload');

You can change the rating before calling 'reload'

'max'

$('.methods-star-rating').star_rating('max', max_value);

You can change the rating before calling 'reload'

'destroy'

$('.methods-star-rating').star_rating('destroy');

This function first calls 'remove', but then also completely destroys the jQuery plugin object (i.e., 'reload' will not work unless it is completely reinitialized)

Configurable Methods

The default configuration includes the following methods/functions that can be customized:

Example:

jQuery(function($) {
	$('.rating').star_rating({
		title: function(clicked_rating, event) {
			return 'Some awesome title instead of the default title';
		}
	});
});

Back to DanielUpshaw.com

Flattr this