WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp star rating

This page is marked as incomplete. You can help Codex by expanding it.

Description

Outputs a HTML element with the star rating exposed on a 0-5 scale in half star increments (i.e. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed in the title attribute by passing the $number parameter.

By default, only works in admin screens.

Usage

<?php wp_star_rating$args ); ?>

Parameters

$args
(array) (optional) array of arguments
Default: 0 stars

Arguments

  • rating - The numeric rating value 0-5 in 0.5 increments. (or 0-100 percent rating for percent type calls) Default 0.
  • type - Acceptable values are 'percent' or the default 'rating'.
  • number - Quantity of submitted ratings, displays as part of title attribute text on hover.

Return Value

(none) 
directly echoes content

Results in a star rating like this:

star-rating.png

Examples

<?php $args = array(
   'rating' => 3.5,
   'type' => 'rating',
   'number' => 1234,
);
wp_star_rating( $args ); ?>

The above code outputs the following HTML:

<div class="star-rating" title="3.5 rating based on 1,234 ratings"><div class="star star-full"></div><div class="star star-full"></div><div class="star star-full"></div><div class="star star-half"></div><div class="star star-empty"></div></div>

Notes

In order to use this function on the front end, your template must include the wp-admin/includes/template.php file and enqueue the appropriate dashicons CSS font information. Example CSS:

@font-face {
	font-family: "dashicons";
	src: url("../fonts/dashicons.eot");
}

@font-face {
	font-family: "dashicons";
	src: url(data:application/x-font-woff;charset=utf-8;base64,/* !! Large amount of data removed, see wp-includes/css/dashicons.css for complete data !! */) format("woff"),
		url("../fonts/dashicons.ttf") format("truetype"),
		url("../fonts/dashicons.svg#dashicons") format("svg");
	font-weight: normal;
	font-style: normal;
}

.star-rating .star-full:before {
    content: "\f155";
}

.star-rating .star-half:before {
    content: "\f459";
}

.star-rating .star-empty:before {
    content: "\f154";
}

.star-rating .star {
    color: #0074A2;
    display: inline-block;
    font-family: dashicons;
    font-size: 20px;
    font-style: normal;
    font-weight: 400;
    height: 20px;
    line-height: 1;
    text-align: center;
    text-decoration: inherit;
    vertical-align: top;
    width: 20px;
}

Note the font data in the above CSS has been omitted for clarity. This data must be included in working code. Refer to wp-admin/css/dashicons.css

Change Log

Since: 3.8

Source File

wp_star_rating() is located in wp-admin/includes/template.php

Related

 

See also index of Function Reference and index of Template Tags.