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

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

Changelog

VersionDescription
4.4.0Introduced the echo parameter.
3.8.0Introduced.

User Contributed Notes

  1. Skip to note 3 content

    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

    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.