wp_star_rating() WordPress Function
The wp_star_rating() function allows you to easily add a star rating system to your Wordpress site. You can use this function to add star ratings to posts, pages, comments, and more. This function is easy to use and is a great way to add an interactive element to your site.
wp_star_rating( array $args = array() ) #
Outputs a HTML element with a star rating for a given rating.
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
- $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
(string) Star rating HTML.
More Information
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
Source
File: wp-admin/includes/template.php
2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 | function wp_star_rating( $args = array() ) { $defaults = array( 'rating' => 0, 'type' => 'rating', 'number' => 0, 'echo' => true, ); $parsed_args = wp_parse_args( $args, $defaults ); // Non-English decimal places when the $rating is coming from a string. $rating = (float) str_replace( ',', '.', $parsed_args['rating'] ); // Convert percentage to star rating, 0..5 in .5 increments. if ( 'percent' === $parsed_args['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 ( $parsed_args['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', $parsed_args['number'] ); $title = sprintf( $format, number_format_i18n( $rating, 1 ), number_format_i18n( $parsed_args['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 ( $parsed_args['echo'] ) { echo $output; } return $output;} |
Expand full source codeCollapse full source codeView on TracView on GitHub
Changelog
| Version | Description |
|---|---|
| 4.4.0 | Introduced the echo parameter. |
| 3.8.0 | Introduced. |