Rating

<pc-rating>

0.1.0

experimental

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

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

Code

Edit

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

Edit

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

Edit

Precision

Use the precision attribute to let users select fractional ratings.

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

Code

Edit

Icon size

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

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

Code

Edit

Readonly

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

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

Code

Edit

Disabled

Use the disabled attribute to disable the rating.

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

Code

Edit

Detecting hover

Use the pc-hover event to 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="rating-detect-hover">
    <pc-rating label="Rating"></pc-rating>
    <span></span>
</div>

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

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

<style>
    .rating-detect-hover span {
        display: inline-block;
        padding: var(--pc-tooltip-padding);
        background-color: var(--pc-tooltip-background-color);
        color: var(--pc-tooltip-color);
        border-radius: var(--pc-tooltip-border-radius);
        font-family: var(--pc-tooltip-font-family);
        font-size: var(--pc-tooltip-font-size);
        font-weight: var(--pc-tooltip-font-weight);
        line-height: var(--pc-tooltip-line-height);
        text-align: start;
        white-space: normal;
        translate: 0.5em -0.25em;
        pointer-events: none;
        user-select: none;
        -webkit-user-select: none;
        box-shadow: var(--pc-shadow-xs);
    }

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

Code

Edit

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)"
></pc-rating>

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

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

Code

Edit

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

Edit

Properties

Name	Description	Default
`label`	A label that describes the rating to assistive devices. Type: `string`	`""`
`value`	The default rating set for the rating. Type: `number`	`0`
`max`	The maximum amount able to be set for the rating. Type: `number`	`5`
`precision`	The precision at which the rating will increase and decrease (e.g., to allow half stars, set the `precision` attribute/property to `0.5`). Type: `number`	`1`
`readonly`	Makes the rating readonly. Type: `boolean`	`false`
`disabled`	Disables the rating. Type: `boolean`	`false`
`getIcon`	A property that customises the icon to be rendered. The first and only argument is the rating’s current value. The property should return a string containing trusted HTML of the icon to render at the specified value. This works well with `<pc-icon>` elements. Type: `(value: number) => string`	‐
`updateComplete`	A read‐only promise that resolves when the component has finished updating.	‐

Learn more about customising animations.

Methods

Name	Description	Arguments
`focus()`	Focuses the rating.	`options: FocusOptions`
`blur()`	Unfocuses the rating (i.e., blurs it).	‐

Learn more about methods.

Events

Name	Description	Event detail
`pc-change`	Emitted when the rating’s value changes.	‐
`pc-hover`	Emitted when the user hovers over a value. The `phase` property indicates when hovering starts, moves to a new value or ends. The `value` property tells what the rating’s value would be if the user were to commit to the hovered value.	`{ phase: "start" \| "move" \| "end", value: number }`

Learn more about events.

Custom properties

Name	Description	Default
`--icon-color`	The inactive colour for icons.	`var(--pc-color-neutral-fill-normal)`
`--icon-color-active`	The active colour for icons.	`var(--pc-color-warning-fill-loud)`
`--icon-size`	The icons’ size.	`1.2rem`

Learn more about customising custom properties.

Parts

Name	Description
`base`	The component’s base wrapper.

Learn more about customising CSS parts.

Importing

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

CDN (script tag)

CDN (import)

npm (import)

To manually import this component from the CDN, copy this code snippet and paste it in your HTML.

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

To manually import this component from the CDN, copy this code snippet and paste it in your JavaScript file.

  import "https://cdn.jsdelivr.net/npm/placer-toolkit@1.0.0-alpha.3/cdn/components/rating/rating.js"; 

To manually import this component from npm, copy this code snippet and paste it in your JavaScript file.

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

Dependencies

This component automatically imports these components:

Icon