wp_star_rating( array $args = array() )
Output a HTML element with a star rating for a given rating.
Description Description
Outputs a HTML element with the star rating exposed on a 0..5 scale in half star increments (ie. 1, 1.5, 2 stars). Optionally, if specified, the number of ratings may also be displayed by passing the $number parameter.
Parameters Parameters
- $args
-
(array) (Optional) Array of star ratings arguments.
- 'rating'
(int|float) The rating to display, expressed in either a 0.5 rating increment, or percentage. Default 0. - 'type'
(string) Format that the $rating is in. Valid values are 'rating' (default), or, 'percent'. Default 'rating'. - 'number'
(int) The number of ratings that makes up this rating. Default 0. - 'echo'
(bool) Whether to echo the generated markup. False to return the markup instead of echoing it. Default true.
Default value: array()
- 'rating'
Return Return
(string) Star rating HTML.
Source Source
File: wp-admin/includes/template.php
function wp_star_rating( $args = array() ) {
$defaults = array(
'rating' => 0,
'type' => 'rating',
'number' => 0,
'echo' => true,
);
$r = wp_parse_args( $args, $defaults );
// Non-English decimal places when the $rating is coming from a string
$rating = (float) str_replace( ',', '.', $r['rating'] );
// Convert Percentage to star rating, 0..5 in .5 increments
if ( 'percent' === $r['type'] ) {
$rating = round( $rating / 10, 0 ) / 2;
}
// Calculate the number of each type of star needed
$full_stars = floor( $rating );
$half_stars = ceil( $rating - $full_stars );
$empty_stars = 5 - $full_stars - $half_stars;
if ( $r['number'] ) {
/* translators: 1: the rating, 2: the number of ratings */
$format = _n( '%1$s rating based on %2$s rating', '%1$s rating based on %2$s ratings', $r['number'] );
$title = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $r['number'] ) );
} else {
/* translators: %s: the rating */
$title = sprintf( __( '%s rating' ), number_format_i18n( $rating, 1 ) );
}
$output = '<div class="star-rating">';
$output .= '<span class="screen-reader-text">' . $title . '</span>';
$output .= str_repeat( '<div class="star star-full" aria-hidden="true"></div>', $full_stars );
$output .= str_repeat( '<div class="star star-half" aria-hidden="true"></div>', $half_stars );
$output .= str_repeat( '<div class="star star-empty" aria-hidden="true"></div>', $empty_stars );
$output .= '</div>';
if ( $r['echo'] ) {
echo $output;
}
return $output;
}
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced the echo parameter. |
| 3.8.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Example
The above code outputs the following HTML:
Usage on the front end
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; }Expand full source codeCollapse full source code
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