Canvas Docs

Star Ratings

Star Ratings

Canvas bundles a star rating plugin that turns a number input into an interactive set of stars, hearts, flags, or custom icons. It supports fractional steps, custom captions, read only and disabled states, and change events.

Setup

Include the bundled stylesheet in the <head> and the plugin script before </body>. Any <input> with the .rating class becomes a star widget.

<!-- In <head> -->
<link rel="stylesheet" href="css/components/bs-rating.css">

<!-- Before </body> -->
<script src="js/components/star-rating.js"></script>

Structure

Use a numeric input with .rating. Configure star count, step, and size through data-* attributes.

<!-- Default 5 star rating -->
<input id="input" type="number" class="rating" max="5" data-size="sm">

<!-- 0.1 step -->
<input id="input-1" type="number" class="rating" max="5" data-step="0.1" data-size="sm">

<!-- 8 stars -->
<input id="input-2" type="number" class="rating" max="8" data-step="1" data-stars="8" data-size="sm">

<!-- Read only -->
<input id="input-15" class="rating" value="1" data-size="sm" data-readonly="true">

<!-- Disabled -->
<input id="input-16" class="rating" value="3" data-size="sm" data-disabled="true">

For custom icons and captions, initialize with rating():

jQuery("#input-7").rating({
  containerClass: 'is-heart',
  filledStar: '<i class="bi-heart-fill"></i>',
  emptyStar: '<i class="bi-heart"></i>',
  starCaptions: {0: "Not Rated", 1: "Very Poor", 2: "Poor", 3: "Ok", 4: "Good", 5: "Very Good"},
  starCaptionClasses: {0: "text-danger", 1: "text-danger", 2: "text-warning", 3: "text-info", 4: "text-primary", 5: "text-success"}
});

Ratings also emit events you can hook into:

jQuery("#input-14").on("rating.change", function(event, value, caption) {
  jQuery("#input-14").rating("refresh", { disabled: true, showClear: false });
});

Options

As data-* attributes:

  • data-stars="5": number of stars.
  • data-step="0.5": rating granularity (1, 0.5, 0.1, etc.).
  • data-size="sm": star size.
  • data-readonly="true": display only, not editable.
  • data-disabled="true": render the control disabled.
  • data-symbol: a custom glyph used for the star.
  • data-default-caption="{rating} Hits": caption template, {rating} is replaced by the value.
  • data-star-captions="{}": per star caption overrides.
  • min / max: the numeric bounds of the underlying input.

As rating({ ... }) options:

  • filledStar / emptyStar: HTML for the filled and empty icons, for example Bootstrap Icons.
  • containerClass: extra class on the widget, for example 'is-heart'.
  • starCaptions: map of value to caption text.
  • starCaptionClasses: map of value to caption CSS class.

Events:

  • rating.change: fires with (event, value, caption) when the rating changes.
  • rating.clear: fires when the rating is reset.

Methods:

  • .rating("refresh", { ... }): re-render with new options, for example to disable after submit.

Tips

  • Swap filledStar and emptyStar for any icon markup to build hearts, flags, or cups instead of stars.
  • Use data-readonly="true" to display existing review scores that users should not change.
Was this page helpful?