Default
You need just to have a div
to build the Raty.
<div></div>
$('div').raty();
Score
Used when we want stars with a saved rating.
$('div').raty({ score: 3 });
Score callback
If you need the starting score to be based on a dynamic value, you can use a callback for it.
You can pass any value for it, not necessarily a data value, for example, you can use a field value.
<div data-score="1"></div>
$('div').raty({
score: function() {
return 2 * 2;
}
});
Score Name
Changes the name of the hidden score field.
$('div').raty({ scoreName: 'entity[score]' });
Data Support
You can pass any data-*
attribute via HTML and Raty will parse it and use it as an option.
<div data-score="3" data-score-name="teacher[teacher_categories][0][value]"></div>
$('div').raty();
Number
Changes the number of stars.
$('div').raty({ number: 10 });
Number callback
You can receive the number of stars dynamic using a callback to set it.
$('div').raty({
number: function() {
return 3;
}
});
Number Max
Change the max number of stars that can be created.
$('div').raty({
numberMax: 5,
number: 100
});
Read Only
You can prevent users from voting. It can be applied with or without a score and all additional stars will show the "hint" stars.
Move 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;
}
});
Not 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.
Hover the mouse over the star to see:
$('div').raty({
readOnly: true,
noRatedMsg: "I'm readOnly and I haven't rated yet!"
});
Half Show
You can represent a float score as a half star icon.
This option is just to show the half star. If you want to enable voting with half stars on mouseover, please check the option half.
The round
options showed below are just for the icon, the score remains a float always.
Enabled
The round
rules are:
- Down: score <= x.25 the star will be rounded down;
- Half: score > x.25 and < x.76 the star will be a half star;
- Up: score >= x.76 the star will be rounded up.
$('div').raty({ score: 1.26 });
Disabled
When halfShow
is disabled, only the option full
(.6
) is checked:
- 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: 1.59
});
Round
You can customize the round values of the halfShow option.
When halfShow
is enabled, only down
and up
is used for round.
You can specify just the attribute you want to change and keep the others as their defaults.
$('div').raty({
round: { down: .26, up: .76 },
score: 1.26
});
Half
Enables the half star mouseover to make voting with half values possible.
If you want to vote with more precision than a half value, please check the option precision.
$('#star').raty({
half: true,
hints: [['bad 1/2', 'bad'], ['poor 1/2', 'poor'], ['regular 1/2', 'regular'], ['good 1/2', 'good'], ['gorgeous 1/2', 'gorgeous']]
});
Star Half
Changes the name of the half star.
Pay attention, when you want to specify a different icon with a different directory, you must to set the path option to null
to prepending the star's original path to your path. You will then have to specify all other icons with their explicit original path.
$('div').raty({
half: true,
starHalf: 'star-half-mono.png'
});
You can change the star icons.
$('div').raty({
cancelButton: true,
starOff: 'star-off-big.png',
starOn: 'star-on-big.png'
});
Click
You can write a callback to handle the score and the click event
on click events.
You can reference 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 the callback, the click event 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 dynamically using callback.
$('div').raty({
path: function() {
return '/assets/vendor/raty';
}
});
Star Off and Star On
Changes the icons.
$('div').raty({
starOff: 'off.png',
starOn: 'on.png'
});
Cancel Button
Add a cancel button on the left side of the stars to cancel the score.
Inside the click callback the argument code receives the value null
when we click on the cancel button.
$('div').raty({ cancelButton: true });
Cancel Button Hint
Like the stars, the cancelButton button has a hint too, and you can change it.
Hover the mouse over the cancel button to see:
$('div').raty({
cancelButton: true,
cancelHint: 'My cancel hint!'
});
Cancel Button Place
Changes the cancelButton button to the right side.
$('div').raty({
cancelButton: true,
cancelPlace: 'right'
});
Cancel off and Cancel On
Changes the on and off icon of the cancel button.
$('div').raty({
cancelButton: true,
cancelOff: 'cancel-off.png',
cancelOn: 'cancel-on.png'
});
Icon Range
Is an array of objects where each one represents a custom icon.
The range
attribute is where the icon will be displayed (out of the five stars).
The on
attribute is the active icon when hovering.
The off
attribute is the default 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
Displays the hints or the cancelButtonHint.
$('div').raty({
cancelButton: 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 options of hint
or score
:
If you choose to see the score instead of the hints using the value score
you will get the numerical value of the star.
For the cancelButton the value is empty.
$('div').raty({
cancelButton: true,
target: '#hint',
targetType: 'score'
});
Target Keep
If you want the score to remain in the hint box after providing the rating, turn on this option.
$('div').raty({
cancelButton: true,
target: '#hint',
targetKeep: true
});
Target Text
Target will blank if you don't use the targetKeep option, after rolling the mouse away from the ratings.
If you want a message to show by default 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 in the target.
$('div').raty({
target: '#hint',
targetFormat: 'Rating: {score}'
});
Target Score
You can keep the score value inside the blank element by default or choose where to put it.
If you change the score target, the default score field won't be created.
This is not a target option for display only, it is the real current score data.
$('div').raty({
targetScore: '#target'
});
Mouseover
You can handle events on mouseover.
The arguments are the same as in 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 exact position of the cursor to get a precise score.
The score is still represented in full and half stars, but the score is saved as a float.
When you enable this option the half option is automatically enabled and targetType is changed to score
.
$('#precision').raty({
cancelButton: true,
cancelOff: 'cancel-off.png',
cancelOn: 'cancel-on.png',
path: 'raty/demo/images',
starHalf: 'star-half.png',
starOff: 'star-off.png',
starOn: 'star-on.png',
target: '#precision-hint',
targetKeep: true,
precision: true
});
Space
You can remove excess space between stars.
$('#space').raty({ space: false });
Single
You can specify the current star being hovered over should be illuminated, instead all preceding stars.
$('#single').raty({ single: true });
Star Type
Lets you to change the star element type. Changing it from img
to i
, for example, changes from an image to a glyph. There is a sample stylesheet (demo/stylesheets/jquery.raty.css
) using a sample fonts (demo/fonts/jquery.raty.[eot|svg|ttf|woff]
).
To be easier to use, we replaced the dot (.) extension to a 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 which allows you to download only the relevant icons only and rename them.
$('div').raty({
cancelButton: true,
half: true,
starType: 'i'
});
Changing the settings globally
You can change any options globally $.fn.raty.defaults.OPTION = VALUE;
. It must be called before you bind the plugin.
$.raty.cancelButton = true;
$.raty.path = 'assets';
Options
cancelButton: false
Creates a cancel button to cancel the rating.
cancelClass: 'raty-cancel'
Name of cancel's class.
cancelHint: 'Cancel this rating!'
The cancel button's 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 (for mixed icons).
mouseout: undefined
Callback executed on mouseout.
mouseover: undefined
Callback executed on mouseover.
noRatedMsg: 'Not rated yet!'
Hint for non rated elements when it's readOnly.
number: 5
Number of stars that will be presented.
numberMax: 20
Max number of stars the option number will create.
path: undefined
A global path where the icon will be found.
precision: false
Enables the selection of a precise score.
readOnly: false
Turns the rating read-only.
round: { down: .25, full: .6, up: .76 }
Includes value attributes to do the score rounding math.
score: undefined
Initial rating.
scoreName: 'score'
Name of the hidden field that holds the score value.
single: false
Enables 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 kept on mouseout.
targetText: ''
Default text in a target.
targetType: 'hint'
Choose if target will receive a hint or the score number.
Functions
$('#star').raty('score');
Get the current score.
$('#star').raty('score', number);
Set a score.
$('#star').raty('click', number);
Click on a star.
$('.star').raty('readOnly', boolean);
Change the read-only state.
$('#star').raty('cancel', boolean);
Cancel the rating. The last param force the click callback.
$('#star').raty('move', number);
Move the mouse to the given score point position.