Rating

Ratings give users a way to quickly view and provide feedback.

<pc-rating label="Rating"></pc-rating>

Code

Demos

Labels

Ratings are commonly identified contextually, so labels aren’t displayed. However, you should always provide one for assistive devices using the label attribute.

<pc-rating label="Rate this component"></pc-rating>

Code

Maximum value

The rating’s maximum value is 5 by default. To change the maximum value, use the max attribute.

<pc-rating label="Rating" max="3"></pc-rating>

Code

Precision

Use the precision attribute to let users select fractional ratings.

<pc-rating label="Rating" precision="0.5" value="2.5"></pc-rating>

Code

Icon size

Set the --icon-size custom property to adjust the size.

<pc-rating label="Rating" style="--icon-size: 2rem"></pc-rating>

Code

Read‐only

Use the readonly attribute to display a rating that users can’t change.

<pc-rating label="Rating" value="3" readonly></pc-rating>

Code

Disabled

Use the disabled attribute to disable the rating.

<pc-rating label="Rating" value="3" disabled></pc-rating>

Code

Detecting hover

Use the pc-hover event ot detect when the user hovers over (or touches and drags) the rating. This lets you hook into values as the user interacts with the rating before they select a value.

This event has a payload with phase and value properties. The phase property tells when hovering starts, moves to a new value and ends. The value property tells what the rating’s value would be if the user were to commit to the hovered value.

<div class="detect-hover">
  <pc-rating label="Rating"></pc-rating>
  <span></span>
</div>

<script>
  const rating = document.querySelector(".detect-hover > pc-rating");
  const span = rating.nextElementSibling;
  const terms = ["No rating", "Terrible", "Bad", "OK", "Good", "Excellent"];

  rating.addEventListener("pc-hover", event => {
      span.textContent = terms[event.detail.value];

      // Clear the feedback when hovering stops
      if (event.detail.phase === "end") {
          span.textContent = "";
      }
  });
</script>

<style>
  .detect-hover span {
      position: relative;
      top: -4px;
      left: 8px;
      padding: var(--pc-spacing-xs) var(--pc-spacing-s);
      text-align: center;
      border-radius: var(--pc-border-radius-s);
      background-color: var(--pc-color-neutral-200);
      color: var(--pc-color-neutral-950);
      box-shadow: var(--pc-shadow-xs);
  }

  .detect-hover span:empty {
      display: none;
  }
</style>

Code

Custom icons

You can provide custom icons by passing a function to the getIcon property.

<pc-rating
  class="rating-hearts"
  label="Rating"
  style="--icon-color-active: var(--pc-color-red-500)"
></pc-rating>

<script>
  const rating = document.querySelector(".rating-hearts");

  rating.getIcon = () => `
      <pc-icon
          library="default"
          icon-style="solid"
          name="heart"
      ></pc-icon>
  `;
</script>

Code

Value‐based icons

You can also use the getIcon property to render different icons based on the value chosen on the rating.

<pc-rating label="Rating" class="rating-emojis"></pc-rating>

<script>
  const rating = document.querySelector(".rating-emojis");

  rating.getIcon = (value) => {
      const icons = [
          "face-angry",
          "face-frown",
          "face-meh",
          "face-smile",
          "face-laugh",
      ];

      return `
          <pc-icon
              library="default"
              icon-style="solid"
              name="${icons[value - 1]}"
          ></pc-icon>
      `;
  };
</script>

Code

Properties

Name	Description	Default
`dependencies`	`object`	`{ "pc-icon": PcIcon }`
`rating`	`HTMLElement`	-
`disabled`	`boolean`	`false`
`label`	`string`	`""`
`max`	`number`	`5`
`precision`	`number`	`1`
`readonly`	`boolean`	`false`
`value`	`number`	`0`
`getIcon`	`(value: number) => string`	-
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	-

Learn more about attributes and properties.

Methods

Name	Description	Arguments
`handleHoverValueChange()`		-
`handleIsHoveringChange()`		-
`focus()`		`options: FocusOptions`
`blur()`		-

Learn more about methods.

Importing

If you’re using the autoloader or the standard loader, you can ignore this section. If you’re cherry picking, you can use any of the following snippets to import this component.

Script

Import

Bundler

To import this component from the CDN with a script tag, copy this snippet and paste it in your HTML.

<script type="module" src="https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/rating/rating.js"></script>

To import this component from the CDN using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "https://cdn.jsdelivr.net/npm/placer-toolkit@0.5.1/dist/components/rating/rating.js";

To import this component with a bundler using a JavaScript import, copy this snippet and paste it in your JavaScript:

import "placer-toolkit/dist/components/rating/rating.js";