wp_star_rating() – Function | Developer.WordPress.org

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

$argsarrayoptional

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:array()

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

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: Hidden accessibility text. 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: Hidden accessibility text. %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;
}

View all references View on Trac View on GitHub

Uses	Description
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.
number_format_i18n()`wp-includes/functions.php`	Converts float number to format based on the locale.

Used by	Description
WP_Customize_Manager::handle_load_themes_request()`wp-includes/class-wp-customize-manager.php`	Loads themes into the theme browsing/installation UI.
WP_Theme_Install_List_Table::install_theme_info()`wp-admin/includes/class-wp-theme-install-list-table.php`	Prints the info for a theme (to be used in the theme installer modal).
install_plugin_information()`wp-admin/includes/plugin-install.php`	Displays plugin information in dialog box form.
WP_Plugin_Install_List_Table::display_rows()`wp-admin/includes/class-wp-plugin-install-list-table.php`	Generates the list table rows.
wp_ajax_query_themes()`wp-admin/includes/ajax-actions.php`	Handles getting themes from themes_api() via AJAX.

Changelog

Version	Description
4.4.0	Introduced the `echo` parameter.
3.8.0	Introduced.

User Contributed Notes

Skip to note 3 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Example
```
<?php $args = array(
   'rating' => 3.5,
   'type' => 'rating',
   'number' => 1234,
);
wp_star_rating( $args ); ?>
```
The above code outputs the following HTML:

[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>
[/html]
Log in to add feedback

Codex 10 years ago

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;
}

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

wp_star_rating( array $args = array() ): string

In this article