Default

You need just to have a div to build the Raty.

<div></div>

$('div').raty();

Score

Used when we want starts with a saved rating.

$('div').raty({ score: 3 });

Score callback

If you need to start you score depending of a dynamic value, you can to use callback for it.
You can pass any value for it, not necessarily a data- value. You can use a field value for example.

<div data-score="1"></div>

$('div').raty({
  score: function() {
    return $(this).attr('data-score');
  }
});

Score Name

Changes the name of the hidden score field.

$('div').raty({ scoreName: 'entity[score]' });

Number

Changes the number of stars.

$('div').raty({ number: 10 });

Number callback

You can receive the number of stars dynamic using callback to set it.

<div data-number="3"></div>

$('div').raty({
  number: function() {
    return $(this).attr('data-number');
  }
});

Number Max

Change the maximum of start that can be created.

$('div').raty({
  numberMax : 5,
  number    : 100
});

Read Only

You can prevent users to vote. It can be applied with or without score and all stars will receives the hint corresponding of the selected star.
Stop the mouse over the stars to see:

$('div').raty({ readOnly: true, score: 3 });

Read Only callback

You can decide if the rating will be readOnly dynamically returning true of false on callback.

$('div').raty({
  readOnly: function() {
    return 'true becomes readOnly' == 'true becomes readOnly';
  }
});

No Rated Message

If readOnly is enabled and there is no score, the hint "Not rated yet!" will be shown for all stars. But you can change it.
Stop the mouse over the star to see:

$('div').raty({
  readOnly   : true,
  noRatedMsg : "I'am readOnly and I haven't rated yet!"
});

Half Show

You can represent a float score as a half star icon.
This options is just to show the half star. If you want enable the vote with half star on mouseover, please check the option half.
The round options showed belows is just for the icon, the score keeps as float always.

Enabled

The round rules are:

  • Down: score <= x.25 the star will be rounded down;
  • Half: score >= x.26 and <= x.75 the star will be a half star;
  • Up: score >= x.76 the star will be rounded up.
$('div').raty({ score: 3.26 });

Disabled

The rules becomes:

  • Down: score < x.6 the star will be rounded down;
  • Up: score >= x.6 the star will be rounded up;
$('div').raty({
  halfShow : false,
  score    : 3.26
});

Round

You can customize the round values of the halfShow option.
We changed the default interval [x.25 .. x.76], now x.26 will round down instead of to be a half star.
Remember that the full attribute is used only when halfShow is disabled.
You can specify just the attribute you want to change and keeps the others as default.

$('div').raty({
  round : { down: .26, full: .6, up: .76 },
  score : 3.26
});

Half

Enables the half star mouseover to be possible vote with half values.
If you want to vote with more precison than half value, please check the option precision.

$('#star').raty({ half: true });

Star Half

Changes the name of the half star.
Pay attention, when you want specify a different icon with a different directory, you must to set the path option to null to avoid it to be prepended on your path and, consequently, specify all other icons with explicit original path.

$('div').raty({
  half     : true,
  starHalf : 'star-half-mono.png'
});

You can to use the size of icon you want.

$('div').raty({
  cancel  : true,
  starOff : 'star-off-big.png',
  starOn  : 'star-on-big.png'
});

Click

Callback to handle the score and the click event on click action.
You can mension the Raty element (DOM) itself using this.

$('div').raty({
  click: function(score, evt) {
    alert('ID: ' + this.id + "\nscore: " + score + "\nevent: " + evt);
  }
});

Click Prevent

If you return false into callback, the click action will be prevented.

$('div').raty({
  click: function(score, evt) {
    alert('Score will not change.')
    return false;
  }
});

Hints

Changes the hint for each star by it position on array.
If you pass null, the score value of this star will be the hint.
If you pass undefined, this position will be ignored and receive the default hint.

$('div').raty({ hints: ['a', null, '', undefined, '*_*']});

Path

Changes the path where your icons are located.
Set it only if you want the same path for all icons.
Don't mind about the last slash of the path, if you don't put it, it will be setted for you.

$('div').raty({ path: 'assets/images' });

Now we have the following full paths: assets/images/star-on.png, assets/images/star-off.png and so.

Path Callback

You can set the path dinamically using callback.

<div data-path="assets/images"></div>

$('div').raty({
  path: function() {
    return this.getAttribute('data-path');
  }
});

Star Off and Star On

Changes the name of the star on and star off.

$('div').raty({
  starOff : 'off.png',
  starOn  : 'on.png'
});

Cancel

Add a cancel button on the left side of the stars to cacel the score.
Inside the click callback the argument code receives the value null when we click on cancel button.

$('div').raty({ cancel: true });

Cancel Hint

Like the stars, the cancel button have a hint too, and you can change it.
Stop the mouse over the cancel button to see:

$('div').raty({
  cancel     : true,
  cancelHint : 'My cancel hint!'
});

Cancel Place

Changes the cancel button to the right side.

$('div').raty({
  cancel      : true,
  cancelPlace : 'right'
});

Cancel off and Cancel On

Changes the on and off icon of the cancel button.

$('div').raty({
  cancel    : true,
  cancelOff : 'cancel-off.png',
  cancelOn  : 'cancel-on.png'
});

Icon Range

It's an array of objects where each one represents a custom icon.
The range attribute is until wich position the icon will be displayed.
The on attribute is the active icon.
The off attribute is the inactive icon.

$('div').raty({
  iconRange: [
    { range: 1, on: '1.png', off: '0.png' },
    { range: 2, on: '2.png', off: '0.png' },
    { range: 3, on: '3.png', off: '0.png' },
    { range: 4, on: '4.png', off: '0.png' },
    { range: 5, on: '5.png', off: '0.png' }
  ]
});

You can use an interval of the same icon jumping some number.
The range attribute must be in an ascending order.
If the value on or off is omitted then the attribute starOn and starOff will be used.

$('div').raty({
  starOff   : '0.png',
  iconRange : [
    { range : 1, on: '1.png' },
    { range : 3, on: '3.png' },
    { range : 5, on: '5.png' }
  ]
});

Now we have all off icons as 0.png, icons 1 and 2 as 1.png, icon 3 as 3.png and icons 4 and 5 as 5.png.

Target

Some place to display the hints or the cancelHint.

$('div').raty({
  cancel : true,
  target : '#hint'
});

Your target can be a div.

<div id="hint"></div>

Your target can be a text field.

<input id="hint" type="text" />

Your target can be a textarea.

<textarea id="hint"></textarea>

Your target can be a select.

<select id="hint">
  <option value="">--</option>
  <option value="bad">bad</option>
  <option value="poor">poor</option>
  <option value="regular">regular</option>
  <option value="good">good</option>
  <option value="gorgeous">gorgeous</option>
</select>

Target Type

You have the option hint or score to chosse.
You can choose to see the score instead the hints using the value score.
For the cancel button the value is empty.

$('div').raty({
  cancel     : true,
  target     : '#hint',
  targetType : 'score'
});

Target Keep

If you want to keep the score into the hint box after you do the rating, turn on this option.

$('div').raty({
  cancel     : true,
  target     : '#hint',
  targetKeep : true
});

Target Text

Normally all target is keeped blank if you don't use the targetKeep option.
If you want a default content you can use this option.

$('div').raty({
  target     : '#hint',
  targetText : '--'
});

Target Format

You can choose a template to be merged with your hints and displayed on target.

$('div').raty({
  target       : '#hint',
  targetFormat : 'Rating: {score}'
});

Target Score

You can keep the score value inside the binded element by default or choose where to put it.
If you change the score target, the default score field won't be created.
It is not like target option for display purpose, it is the real current score data.

$('div').raty({
  targetScore: '#target'
});

Mouseover

You can handle the action on mouseover.
The arguments is the same of the click callback.
The options target, targetFormat, targetKeep, targetText and targetType are abstractions of this callback. You can do it by yourself.

$('div').raty({
  mouseover: function(score, evt) {
    alert('ID: ' + this.id + "\nscore: " + score + "\nevent: " + evt);
  }
});

Mouseout

You can handle the action on mouseout.
The arguments is the same of the mouseover callback.

$('div').raty({
  mouseout: function(score, evt) {
    alert('ID: ' + this.id + "\nscore: " + score + "\nevent: " + evt);
  }
});

Precision

You can get the right position of the cursor to get a precision score.
The star is represented just as half and full star, but the score is saved with precision.
When you enable this option the half options is automatically enabled and targetType is changed to score.

$('#precision').raty({
  cancel     : true,
  cancelOff  : 'cancel-off.png',
  cancelOn   : 'cancel-on.png',
  path       : 'images',
  starHalf   : 'star-half.png',
  starOff    : 'star-off.png',
  starOn     : 'star-on.png',
  target     : '#precision-hint',
  targetKeep : true,

  precision  : true
});

Space

You can take off the space between the star.

$('#space').raty({ space: false });

Single

You can turn on just the mouseovered star instead all from the first until that one.

$('#single').raty({ single: true });

Star Type

It lets you to change the star element type. Changing it from img to i, for example, gives you the change to use font instead image. There is a sample CSS (stylesheets/jquery.raty.css) using a sample fonts (fonts/jquery.raty.[eot|svg|ttf|woff]).

To be easier to use, we replace the dot (.) extension to hyphen (-), so you do not need to change the original names, just set the names to your fonts. We recommend you use the Ico Moon app to be possible to download only the icons you need and rename it.

$('div').raty({
  cancel   : true,
  half     : true,
  starType : 'i'
});

Changing the settings globally

You can change any option mentioning the scope $.fn.raty.defaults.OPTION = VALUE;. It must be called before you bind the plugin.

$.fn.raty.defaults.path = assets;
$.fn.raty.defaults.cancel = true;

Options

cancel: false

Creates a cancel button to cancel the rating.

cancelClass: 'raty-cancel'

Name of cancel's class.

cancelHint: 'Cancel this rating!'

The cancel's button hint.

cancelOff: 'cancel-off.png'

Icon used on active cancel.

cancelOn: 'cancel-on.png'

Icon used inactive cancel.

cancelPlace: 'left'

Cancel's button position.

click: undefined

Callback executed on rating click.

half: false

Enables half star selection.

halfShow: true

Enables half star display.

hints: ['bad', 'poor', 'regular', 'good', 'gorgeous']

Hints used on each star.

iconRange: undefined

Object list with position and icon on and off to do a mixed icons.

mouseout: undefined

Callback executed on mouseout.

mouseover: undefined

Callback executed on mouseover.

noRatedMsg: 'Not rated yet!'

Hint for no rated elements when it's readOnly.

number: 5

Number of stars that will be presented.

numberMax: 20

Max of star the option number can creates.

path: undefined

A global locate where the icon will be looked.

precision: false

Enables the selection of a precision score.

readOnly: false

Turns the rating read-only.

round: { down: .25, full: .6, up: .76 }

Included values attributes to do the score round math.

score: undefined

Initial rating.

scoreName: 'score'

Name of the hidden field that holds the score value.

single: false

Enables just a single star selection.

space: true

Puts space between the icons.

starHalf: 'star-half.png'

The name of the half star image.

starOff: 'star-off.png'

Name of the star image off.

starOn: 'star-on.png'

Name of the star image on.

target: undefined

Element selector where the score will be displayed.

targetFormat: '{score}'

Template to interpolate the score in.

targetKeep: false

If the last rating value will be keeped after mouseout.

targetText: ''

Default text setted on target.

targetType: 'hint'

Option to choose if target will receive hint or the score number.

Functions

$('#star').raty('score');

Get the current score. If there is no score then undefined will be returned.

$('#star').raty('score', number);

Set a score.

$('#star').raty('click', number);

Click on some star. It always call the click callback if it exists.

$('.star').raty('readOnly', boolean);

Change the read-only state.

$('#star').raty('cancel', boolean);

Cancel the rating. The boolean parameter tells if the click will be called or not. If you ommit it, false it will be.

$('#star').raty('reload');

Reload the rating with the same configuration it was binded.

$('#star').raty('set', { option: value });

Reset the rating with new configurations. Only options especified will be overrided.

$('#star').raty('destroy');

Destroy the bind and gives you the raw element before the bind.

$('#star').raty('move', number);

Move the mouse to the given score point position.

Functions demo

run
run
run
run
run
run
run
run
run
run