The StarRating widget is a wrapper for the Bootstrap Star Rating JQuery Plugin designed by Krajee. This plugin is a simple yet powerful JQuery star rating plugin for Bootstrap. Developed with a focus on utlizing pure CSS-3 styling to render the control.
\kartik\widgets
namespace, this widget can be also installed from the yii2-widget-rating repository
and can also be accessed via \kartik\rating\StarRating
namespace.
Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)
StarRating
supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the StarRating::bsVersion
property to one of the following.
To use with bootstrap 3 library - you can set StarRating::bsVersion
property to any string starting with 3 (e.g. 3
or 3.3.7
or 3.x
)
To use with bootstrap 4 library - you can set StarRating::bsVersion
property to any string starting with 4 (e.g. 4
or 4.6.0
or 4.x
)
To use with bootstrap 5 library - you can set StarRating::bsVersion
property to any string starting with 5 (e.g. 5
or 5.1.0
or 5.x
)
Generally, you may also want to set a default version globally for all Krajee Extensions (instead of setting it for each widget or extension separately). In order to do this, you can setup the bsVersion
property within Yii 2 application params (i.e. Yii::$app->params['bsVersion']
). To set this up, add this section of code to your application params configuration file (e.g. config/params.php
):
'params' => [ 'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions // other settings // 'adminEmail' => 'admin@example.com' ]
If StarRating::bsVersion
property is set, in addition to Yii::$app->params['bsVersion']
, the extension level setting (StarRating::bsVersion
property) will override the Yii::$app->params['bsVersion']
. If StarRating::bsVersion
property is not set, and Yii::$app->params['bsVersion']
is also not set, StarRating::bsVersion
property will default to 3.x
(i.e. Bootstrap 3.x version will be assumed as default).
You need to install one of yiisoft/yii2-bootstrap
or yiisoft/yii2-bootstrap4
or yiisoft/yii2-bootstrap5
extensions manually in your application to enable Bootstrap 3.x or 4.x or 5.x functionality respectively. This dependency has not been pre-built into the composer configuration for Krajee extensions, to allow better control to the developers in configuring their bootstrap library version. If bsVersion
is set to 5.x
and yiisoft/yii2-bootstrap5
is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap5
extension. If bsVersion
is set to 4.x
and yiisoft/yii2-bootstrap4
is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap4
extension. Similarly, if bsVersion
is set to 3.x
and yiisoft/yii2-bootstrap
is not installed, an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap
extension.
To install yiisoft/yii2-bootstrap5
, add the repo to the require
section of your application's composer.json.
"yiisoft/yii2-bootstrap5": "@dev"
To install yiisoft/yii2-bootstrap4
, add the repo to the require
section of your application's composer.json.
"yiisoft/yii2-bootstrap4": "@dev"
To install yiisoft/yii2-bootstrap
, add the repo to the require
section of your application's composer.json.
"yiisoft/yii2-bootstrap": "@dev"
The Krajee extension asset bundle(s) by default depend on one of the following asset bundles to load the Bootstrap CSS and JS:
yii\bootstrap\BootstrapAsset
and/or yii\bootstrap\BootstrapPluginAsset
for bootstrap 3.x (bsVersion = 3
setting)
yii\bootstrap4\BootstrapAsset
and/or yii\bootstrap4\BootstrapPluginAsset
for bootstrap 4.x ( bsVersion = 4
setting)
yii\bootstrap5\BootstrapAsset
and/or yii\bootstrap5\BootstrapPluginAsset
for bootstrap 5.x (bsVersion = 5
setting)
This is controlled by the property bsDependencyEnabled
within the asset bundle (which defaults to true
). One can override this and prevent the default yii2 bootstrap assets (CSS & JS) from loading by doing one or all of the following:
Global Override: Set Yii::$app->params['bsDependencyEnabled']
to false
in your Yii 2 application config params.php
. This setting will be applied for all Krajee Extension Asset Bundles that depend on Bootstrap assets.
'params' => [ 'bsDependencyEnabled' => false, // this will not load Bootstrap CSS and JS for all Krajee extensions // you need to ensure you load the Bootstrap CSS/JS manually in your view layout before Krajee CSS/JS assets // // other params settings below // 'bsVersion' => '5.x', // 'adminEmail' => 'admin@example.com' ]
Asset Bundle Specific Override: Set bsDependencyEnabled
to false
for the specific asset bundle within Yii2 Asset Manager component in your Yii 2 application config file.
// ... 'components' => [ 'assetManager' => [ 'bundles' => [ 'kartik\form\ActiveFormAsset' => [ 'bsDependencyEnabled' => false // do not load bootstrap assets for a specific asset bundle ], ], ], ],
When setting bsDependencyEnabled
to false
, you need to ensure that your app code/view layout loads the Bootstrap CSS and JS on your view before the Krajee CSS/JS are loaded to ensure that the Krajee extension JS plugins and CSS styles do not get broken.
Bootstrap 5.x / 4.x does not include glyphicons or any other icons framework bundled with the library. Krajee extensions therefore will use Font Awesome 5.x icons instead of glyphicons when working with Bootstrap 5.x / 4.x. You can download Font Awesome 5.x icons from the icons website. Alternatively, you can load the free version of Font Awesome from their CDN.
For Krajee extensions and demos, the Font Awesome Free version is used and loaded as the Icons Display Package on all the Yii2 demo layouts. To include font awesome assets on your page, include the following markup on the HEAD
section of your view layout file, when bsVersion
is set to 4.x
or 5.x
.
Option 1: Font CSS version of Font Awesome:
<!-- on your view layout file HEAD section --> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css">
Option 2: SVG / JS version of Font Awesome (recommended for cleaner scaling vector icons and features like icon layers):
<!-- on your view layout file HEAD section --> <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js" crossorigin="anonymous"></script>
Alternatively, you can use the FontAwesomeAsset
from the kartik-v/yii2-icons
package to load the SVG/JS version.
// on your view layout file use kartik\icons\FontAwesomeAsset; FontAwesomeAsset::register($this);
The yii2-widget-rating
extension can be installed automatically or manually using one of these options:
Installation via Composer is the recommended and most easy option to install Krajee Yii2 extensions. You can install yii2-widget-rating
via composer
package manager. Either run:
$ php composer.phar require kartik-v/yii2-widget-rating "dev-master"
or add:
"kartik-v/yii2-widget-rating": "dev-master"
to your application's composer.json
file.
You may also manually install the extension to your project (in case your composer install does not work). Just download the source ZIP or TAR ball and extract the extension asset files and folders into your project. You may need to install dependencies manually and also set the namespaces to the extensions in your Yii2 extensions configurations manually.
bsVersion
:
string | int, the bootstrap library version to be used for the extension. Refer the Bootstrap Info section for details and pre-requisites on setting this property.
To use with Bootstrap library - you can set this to any string starting with
3
(e.g. 3
or 3.3.7
or 4.x / 3.x
)
To use with bootstrap 4 - you can set this to any string starting with
4
(e.g. 4
or 4.6.0
or 4.x
)
To use with bootstrap 5 - you can set this to any string starting with
4
(e.g. 5
or 5.1.0
or 5.x
)
bsColCssPrefixes
:
array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface
. If not set will default to:.
[ 3 => [ self::SIZE_X_SMALL => 'col-xs-', self::SIZE_SMALL => 'col-sm-', self::SIZE_MEDIUM => 'col-md-', self::SIZE_LARGE => 'col-lg-', self::SIZE_X_LARGE => 'col-lg-', self::SIZE_XX_LARGE => 'col-lg-', ], 4 => [ self::SIZE_X_SMALL => 'col-', self::SIZE_SMALL => 'col-sm-', self::SIZE_MEDIUM => 'col-md-', self::SIZE_LARGE => 'col-lg-', self::SIZE_X_LARGE => 'col-xl-', self::SIZE_XX_LARGE => 'col-xl-', ], 5 => [ self::SIZE_X_SMALL => 'col-', self::SIZE_SMALL => 'col-sm-', self::SIZE_MEDIUM => 'col-md-', self::SIZE_LARGE => 'col-lg-', self::SIZE_X_LARGE => 'col-xl-', self::SIZE_XX_LARGE => 'col-xxl-', ], ];
disabled
: boolean whether the input widget is to be entirely disabled. Defaults to false
.
readonly
: boolean whether the input widget is to be entirely readonly. Defaults to false
.
options
: array the HTML attributes for the widget input tag.
pluginOptions
: array the plugin settings/options for the Bootstrap Star Rating Plugin. There are a quite a few options you can set in this plugin. Refer the plugin documentation and demos for details.
pluginEvents
: array the StarRating JQuery events. You must define events in
event-name
=> event-function
format. All events will be stacked in the sequence.
Refer the plugin documentation and demos for details. For example:
pluginEvents = [ "rating.change" => "function() { log("rating.change"); }", "rating.clear" => "function() { log("rating.clear"); }", "rating.reset" => "function() { log("rating.reset"); }", ];
Usage with ActiveForm and model. Note the model validation is activated for this field (integers only and min 1 and max 5).
Fractional ratings increasing by 0.1. Uses the default unicode star symbol instead of glyphicon star.
A disabled star rating input with an initial value.
Set the language / locale for translation.
Render a display only rating easily
RTL rating with no caption.
use kartik\widgets\StarRating // Usage with ActiveForm and model. Note the model validation is activated for // this field (integers only and min 1 and max 5). echo $form->field($model, 'rating')->widget(StarRating::classname(), [ 'pluginOptions' => ['step' => 0.1] ]); // Fractional ratings increasing by 0.1. Uses the // default unicode star symbol instead of glyphicon star. echo '<label class="control-label">Rating</label>'; echo StarRating::widget(['model' => $model, 'attribute' => 'rating_1', 'pluginOptions' => [ 'theme' => 'krajee-uni', 'filledStar' => '★', 'emptyStar' => '☆' ] ]); // A disabled star rating input with initial value echo '<label class="control-label">Rating</label>'; echo StarRating::widget([ 'name' => 'rating_2', 'value' => 2.5, 'disabled' => true ]); // Set the language / locale for translation echo StarRating::widget([ 'name' => 'rating_33', 'value' => 3, 'language' => 'de' ]); // Render a display only rating easily echo StarRating::widget([ 'name' => 'rating_35', 'value' => 3, 'pluginOptions' => ['displayOnly' => true] ]);
Fractional star rating with 6 stars , custom star symbol (uses glyphicon heart), custom captions, and customizable ranges.
Set size of the control to extra large and reduce number of stars
Set a preset value, make it readonly, hide caption, and hide clear button.
Control the number of stars, each caption value, and styles for display
Advanced theming and ability to use richer markup (e.g. SVG). Use the inbuilt Krajee SVG theme for rendering SVG icons.
use kartik\widgets\StarRating use yii\web\JsExpression; // Fractional star rating with 6 stars , custom star symbol (uses glyphicon heart), // custom captions, and customizable ranges. echo StarRating::widget(['name' => 'rating_19', 'pluginOptions' => [ 'stars' => 6, 'min' => 0, 'max' => 6, 'step' => 0.1, 'filledStar' => '<i class="fas fa-heart"></i>', 'emptyStar' => '<i class="fas fa-heart-empty"></i>', 'defaultCaption' => '{rating} hearts', 'starCaptions' => new JsExpression("function(val){return val == 1 ? 'One heart' : val + ' hearts';}") ] ]); // Set size of the control to extra large and reduce number of stars echo StarRating::widget([ 'name' => 'rating_20', 'pluginOptions' => [ 'size' => 'xl', 'stars' => 3, 'min' => 0, 'max' => 3 ], ]); // Set a preset value, make it readonly, hide caption, and hide clear button. echo StarRating::widget([ 'name' => 'rating_21', 'value' => 2, 'pluginOptions' => [ 'readonly' => true, 'showClear' => false, 'showCaption' => false, ], ]); // Control the number of stars, each caption value, and styles for display echo StarRating::widget([ 'name' => 'rating_21', 'pluginOptions' => [ 'min' => 0, 'max' => 12, 'step' => 2, 'size' => 'lg', 'starCaptions' => [ 0 => 'Extremely Poor', 2 => 'Very Poor', 4 => 'Poor', 6 => 'Ok', 8 => 'Good', 10 => 'Very Good', 12 => 'Extremely Good', ], 'starCaptionClasses' => [ 0 => 'text-danger', 2 => 'text-danger', 4 => 'text-warning', 6 => 'text-info', 8 => 'text-primary', 10 => 'text-success', 12 => 'text-success' ], ], ]); // Advanced theming and ability to use richer markup (e.g. SVG). // Use the inbuilt Krajee SVG theme for rendering SVG icons echo StarRating::widget(['name' => 'rating_44', 'pluginOptions' => [ 'theme' => 'krajee-svg', 'filledStar' => '<span class="krajee-icon krajee-icon-star"></span>', 'emptyStar' => '<span class="krajee-icon krajee-icon-star"></span>' ] ]);
Comments & Discussion
Note
You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.
The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.