WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

wp_star_rating()

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

In this article

Back to top

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

UsesDescription
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 byDescription
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

VersionDescription
4.4.0Introduced the echo parameter.
3.8.0Introduced.

User Contributed Notes

  1. Skip to note 3 content
    Codex
    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]

  2. Skip to note 4 content
    Codex
    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

    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

You must log in before being able to contribute a note or feedback.