jQuery Raty - A Star Rating Plugin

Default options:

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

<div id="star"></div>

Started with a score and read only value:

$('#star').raty({
readOnly: true,
start: 2
});

<div id="star"></div>

Starting with a callback:

$('#start').raty({
  start: function() {
    return $(this).attr('data-rating');
  }
});

<div id="star" data-rating="3"></div>

A hint for no rated elements when it's read-only:

$('#star').raty({
readOnly: true,
noRatedMsg: 'anyone rated this product yet!'
});

<div id="star"></div>

Custom score name and a number of stars:

$('#star').raty({
scoreName: 'entity.score',
number: 10
});

<div id="star"></div>

Using click function:

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

<div id="star"></div>

- The argument score is the selected value;
- The argument evt is the click event;
- You can mension the star element (DOM) itself using 'this'.

Default cancel button:

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

<div id="star"></div>

- The score value for the click on cancel button is null.

Custom cancel button:

$('#star').raty({
  cancel:      true,
  cancelHint:  'remove my rating!',
  cancelPlace: 'right',
  click: function(score, evt) {
    alert('score: ' + score);
  }
});

<div id="star"></div>

Half star voting:

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

<div id="star"></div>

- You can disable the 'halfShow' option to just vote with half star but not show it.
- If 'halfShow' is disabled, then score >= x.6 will be rounded up visually.
- The interval can be:
-- Rounded down: [x.00 .. x.25]
-- Half star: [x.26 .. x.75]
-- Rounded up: [x.76 .. x.99]

Custom round option:

$('#star').raty({
start: 1.26,
round: { down: .25, full: .6, up: .76 }
});

<div id="star"></div>

- This example use the default round values;
- down: with halfShow enabled, score <= x.25 will be rounded down; (inclusive)
- up: with halfShow enabled, score >= x.76 will be rounded up; (inclusive)
- down-up: with halfShow enabled, score > x.25 and score < .76 will be half star; (inclusive)
- full: with halfShow disabled, score >= x.6 will be rounded up; (inclusive)

Custom hint and icons:

$('#star').raty({
  hintList: ['a', '', null, 'd', '5'],
  starOn:   'medal-on.png',
  starOff:  'medal-off.png'
});

<div id="star"></div>

- To display the number of the star, set null.

Range of custom icons:

$('#star').raty({
  iconRange: [
    { range: 2, on: 'face-a.png', off: 'face-a-off.png' },
    { range: 3, on: 'face-b.png', off: 'face-b-off.png' },
    { range: 4, on: 'face-c.png', off: 'face-c-off.png' },
    { range: 5, on: 'face-d.png', off: 'face-d-off.png' }
  ] });

<div id="star"></div>

- It's a array of objects where each one represents a custom icon;
- The value range is until wich position the icon will be displayed;
- The value on is the active icon;
- The value off is the inactive icon;
- The sequence of the range interval should be in a ascending order;
- If the value on or off is omitted then the attribute starOn or starOff will be used.

Bigger icon:

$('#star').raty({
  cancel:    true,
  cancelOff: 'cancel-off-big.png',
  cancelOn:  'cancel-on-big.png',
  half:      true,
  size:      24,
  starHalf:  'star-half-big.png',
  starOff:   'star-off-big.png',
  starOn:    'star-on-big.png'
});

<div id="star"></div>

- You can specify your own width as following: width: 120.

Group of elements:

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

<div class="star"></div>
<div class="star"></div>
<div class="star"></div>

- The ID is optional and must be unique;
- If you don't pass a ID for the element, then it will be created.

Displaying hint in a target element:

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

<div id="star"></div>
<div id="target"></div>

Displaying and keeping the score in a target element:

$('#star').raty({
  cancel:     true,
  target:     '#score',
  targetKeep: true,
  targetType: 'number'
});

<select id="target">
  <option value="">0</option>
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
</select>

- You can to choose the target types 'hint' or 'number'.

Setting default value to the target on mouseout:

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

<div id="star"></div>
<div id="target"></div>

Displaying hint with format template:

$('#star').raty({
  cancel:       true,
  cancelHint:   'Sure?',
  target:       '#hint',
  targetFormat: 'your score: {score}',
  targetText:   'none',
  targetKeep:    true
});

<div id="star"></div>
<div id="target"></div>

Half star voting precision:

$('#star').raty({
  half:       true,
  precision:  true,
  size:       24,
  starHalf:   'star-half-big.png',
  starOff:    'star-off-big.png',
  starOn:     'star-on-big.png'
  target:     '#precision-target'
  targetType: 'number'
});

<div id="star"></div>
<div id="target"></div>

Without space between stars:

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

<div id="star"></div>

Single icon:

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

<div id="star"></div>

Directed actions with public functions:

love:

happy:

your last rate:

$('.star').raty({
  half:  true,
  click: function(score, evt) {
    $(this).raty('cancel');
    $('#result').raty('start', score);
  }
});

<div class="star"></div>
<div class="star"></div>

<div id="result"></div>

- All public functions have a optional second parameter to specify which container will be executed;
- You can pass a ID or a class to be the target of the action;
- If the ID or class are not specified, then the last element Raty will be takes.

Public functions:

Start 1 | Start 2 | Start 3 | Start 4 | Start 5

Click 1 | Click 2 | Click 3 | Click 4 | Click 5

ReadOnly (true) | ReadOnly (false)

Cancel | Cancel (trigger)

Changing the settings globally:

$.fn.raty.defaults.starOn = 'star-on.gif';
$.fn.raty.defaults.starOff = 'star-off.gif';

- You can change any option mention the scope $.fn.raty.defaults. + option_name;
- This setup must be called before you bind the Raty, of course.

Default options:

cancel: false

If will be showed a button to cancel the rating.

cancelHint: 'cancel this rating!'

The hint information.

cancelOff: 'cancel-off.png'

Name of the cancel image off.

cancelOn: 'cancel-on.png'

Name of the cancel image on.

cancelPlace: 'left'

Position of the cancel button.

click: undefined

Function that returns the selected value.

half: false

Enables half star selection.

halfShow: true

Enables half star display.

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

List of names that will be used as a hint on each star.

iconRange: undefined

List of object that represent each icon with position and names.

noRatedMsg: 'not rated yet'

A hint for no rated elements when it's read-only.

number: 5

Number of stars that will be presented.

path: 'img/'

A range of custom icons that you can set.

readOnly: false

If the stars will be read-only.

scoreName: 'score'

Name of the hidden field that holds the score value.

size: 16

The icons size.

starHalf: 'star-half.png'

The name of the half star image.

space: true

Option to take off the spaces between the star.

starOff: 'star-off.png'

Name of the star image off.

starOn: 'star-on.png'

Name of the star image on.

start: 0

Number of stars to be selected.

target: undefined

Number of stars to be selected.

targetKeep: false

If the last choose value will be keeped on mouseout.

targetText: ''

Default value when there is no score or targetKeep is off.

targetType: 'hint'

What display on target element: hint or number.

width: undefined

The container width of the stars.

Public functions:

$('#star').raty('start', 3);

Starts the last Raty with 3 stars.

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

Click on the second star of the Raty with ID called 'raty'.

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

Adjusts all Raty with class called 'raty' for read-only.

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

Cancel the rating. The second optional parameter enable thes click callback.

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

Recovers the current score. For class returns an array. No rated returns null.