The Placer Toolkit alpha has arrived! 🎉
Plenty of changes are coming your way—some big, some breaking, some even nuclear! Beware the changelog…

Bring it on!

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 attributes and properties.

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.1/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.1/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