Rating

<pc-rating>

0.1.0

experimental

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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

Eigenschaften#

Name	Beschreibung	Standard
`label`	A label that describes the rating to assistive devices. Typ: `string`	`""`
`value`	The default rating set for the rating. Typ: `number`	`0`
`max`	The maximum amount able to be set for the rating. Typ: `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`). Typ: `number`	`1`
`readonly`	Makes the rating readonly. Typ: `boolean`	`false`
`disabled`	Disables the rating. Typ: `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. Typ: `(value: number) => string`	‐
`updateComplete`	Ein schreibgeschütztes Promise, das erfüllt ist, sobald die Komponente fertig aktualisiert wurde.	‐

Erfahre mehr über Attribute und Eigenschaften.

Methoden#

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

Erfahre mehr über Methoden.

Events#

Name	Beschreibung	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 }`

Erfahre mehr über Events.

Benutzerdefinierte Eigenschaften#

Name	Beschreibung	Standard
`--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`

Erfahre mehr über das Anpassen von benutzerdefinierten Eigenschaften.

Parts#

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

Erfahre mehr über das Anpassen von CSS‐Parts.

Importieren#

Wenn du den Autoloader oder den Standard‐Loader nutzt, kannst du diesen Abschnitt überspringen. Falls du „Cherry Picking“ betreibst, kannst du die folgenden Snippets verwenden, um diese Komponente zu importieren.

CDN (Skript‐Tag)

CDN (Import)

npm (Import)

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in dein HTML ein.

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

Um diese Komponente manuell vom CDN zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

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

Um diese Komponente manuell via npm zu importieren, kopiere dieses Code‐Snippet und füge es in deine JavaScript‐Datei ein.

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

Abhängigkeiten#

Diese Komponente importiert automatisch folgende Komponenten:

Icon