Rating

<quiet-rating>

stable

since 1.0

Ratings let users provide feedback based on their satisfaction with a product or service.

<quiet-rating 
  label="Rate my cat"
  description="Leave her some stars."
  name="cat"
  value="4"
>
</quiet-rating>

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the rating. If you want to provide HTML, use the label and description slots instead.

For details, please visit our website.

<quiet-rating name="name" label="How would you rate our catnip?">
  <span slot="description">
    For details, please <a href="https://example.com/" target="_blank">visit our website</a>.
  </span>
</quiet-rating>

Providing an initial value Jump to heading

Use the value attribute to provide an initial value for the rating.

<quiet-rating 
  name="food" 
  label="Food quality" 
  value="3"
></quiet-rating>

Changing the scale Jump to heading

Ratings use a scale of 1–5 by default. You can change this by setting the max attribute.

<quiet-rating 
  name="litter" 
  label="Cleanliness of litter box area" 
  max="3" 
  value="3"
></quiet-rating>

Fractional values Jump to heading

You can enable fractional values by setting the step attribute. For example, 0.5 will allow half-star ratings.

<quiet-rating 
  name="stars"
  label="Half-stars are fine" 
  step=".5" 
  value="2.5"
></quiet-rating>

Changing the size Jump to heading

Use the size attribute to change the rating's size.

<quiet-rating size="xs" label="Extra small"></quiet-rating><br>
<quiet-rating size="sm" label="Small"></quiet-rating><br>
<quiet-rating size="md" label="Medium"></quiet-rating><br>
<quiet-rating size="lg" label="Large"></quiet-rating><br>
<quiet-rating size="xl" label="Extra large"></quiet-rating>

Using custom symbols Jump to heading

To customize the symbols shown, use JavaScript to set the getSymbol property to a function that returns the HTML for each symbol. The function will receive the value and isSelected arguments that you can use to customize the symbol based on specific values or whether the symbol is in the selected state.

<quiet-rating 
  label="Show some love" 
  id="rating__custom-symbols" 
  value="3"
  style="
    --symbol-selected-color: deeppink;
    --symbol-unselected-color: gray;
  "
></quiet-rating>

<script>
  const rating = document.getElementById('rating__custom-symbols');

  rating.getSymbol = (value, isSelected) => {
    return isSelected ? 
      `<quiet-icon family="filled" name="heart"></quiet-icon>` : 
      `<quiet-icon family="outline" name="heart"></quiet-icon>`;
  }
</script>

<quiet-rating 
  label="How satisfied are you?" 
  id="rating__numbers" 
  value="3"
  style="--symbol-selected-color: dodgerblue;"
></quiet-rating>

<script>
  const rating = document.getElementById('rating__numbers');

  rating.getSymbol = (value, isSelected) => {
    const family = isSelected ? 'filled' : 'outline';
    return `<quiet-icon family="${family}" name="square-number-${value}"></quiet-icon>`
  }
</script>

<quiet-rating 
  label="How satisfied are you?" 
  id="rating__diamonds" 
  value="3"
  style="--symbol-selected-color: #2bb7d1;"
></quiet-rating>

<script>
  const rating = document.getElementById('rating__diamonds');

  rating.getSymbol = (value, isSelected) => {
    const family = isSelected ? 'filled' : 'outline';
    const name = isSelected ? 'diamond' : 'point'
    return `<quiet-icon family="${family}" name="${name}"></quiet-icon>`
  }
</script>

You should only return trusted HTML from the getSymbol() function, otherwise you may become vulnerable to XSS exploits.

Readonly ratings Jump to heading

Use the readonly attribute to make the rating read-only.

<quiet-rating label="Read-only" value="4" readonly></quiet-rating>

Disabling Jump to heading

Use the disabled attribute to disable the rating.

<quiet-rating label="Disabled" value="4" disabled></quiet-rating>

Validation Jump to heading

The required attribute can be applied to enable validation using the Constraint Validation API. This will prevent form submission until a non-zero value is selected.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-rating name="required" label="Required" required></quiet-rating><br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the custom-validity attribute to make the rating invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, remove the attribute or set it to an empty string.

<form action="about:blank" method="get" target="_blank">
  <quiet-rating 
    name="food" 
    label="Food quality" 
    value="3"
    custom-validity="Not so fast, bubba!"
  ></quiet-rating>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

Most validation attributes work exactly like their native counterparts. However, the custom-validity attribute is offered in lieu of the setCustomValidity() method. This allows you to declaratively set custom errors instead of having to call a method with JavaScript.

Styling validation Jump to heading

You can style valid and invalid ratings using the :valid and :invalid pseudo classes.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="rating__validation-pseudo">
  <quiet-rating 
    name="food" 
    label="Food quality" 
    description="This field is required."
    required
  ></quiet-rating>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .rating__validation-pseudo {
    quiet-rating:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-rating:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to fill out the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

              
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="rating__validation-custom">
  <quiet-rating 
    name="food" 
    label="Food quality" 
    description="This field is required."
    required
  ></quiet-rating>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .rating__validation-custom {
    quiet-rating:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-rating:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-rating> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet@1.0.0/dist/components/rating/rating.js';

To manually import <quiet-rating> from npm, use the following code.

import '@quietui/quiet/dist/components/rating/rating.js';

Slots Jump to heading

Rating supports the following slots. Learn more about using slots

Name	Description
`label`	The rating's label. For plain-text labels, you can use the `label` attribute instead.
`description`	The rating's description. For plain-text descriptions, you can use the `description` attribute instead.

Properties Jump to heading

Rating has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`associatedForm`	A reference to the `<form>` associated with the form control, or `null` if no form is associated.	`HTMLFormElement null`	`null`
`label`	The rating's label. If you need to provide HTML in the label, use the `label` slot instead.	`string`
`description`	The rating's description. If you need to provide HTML in the description, use the `description` slot instead.	`string`
`name`	The name of the rating. This will be submitted with the form as a name/value pair.	`string`
`value`	The rating's value.	`number`	`0`
`disabled`	Disables the rating.	`boolean`	`false`
`readonly`	Makes the rating a read-only field.	`boolean`	`false`
`size`	The rating's size.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`form`	The form to associate this control with. If omitted, the closest containing `<form>` will be used. The value of this attribute must be an iD of a form in the same document or shadow root.	`string`
`required`	Makes the rating required. Form submission will not be allowed when this is set and the rating is empty.	`boolean`	`false`
`max`	The maximum value allowed.	`number`	`5`
`step`	The granularity the value must adhere to when incrementing and decrementing.	`number`	`1`
`customValidity` `custom-validity`	You can provide a custom error message to force the rating to be invalid. To clear the error, set this to an unselected string.	`string`	`''`
`autofocus`	Tells the browser to focus the rating when the page loads or a dialog is shown.	`boolean`
`getSymbol`	A function that returns the HTML for each symbol. The function will receive the `value` and `isSelected` arguments that you can use to customize the symbol based on specific values or whether the symbol is in the selected state. You should only return trusted HTML from this function, otherwise you may become vulnerable to XSS exploits.	`(step: number, isSelected: boolean) => string`

Methods Jump to heading

Rating supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`focus()`	Sets focus to the rating.
`blur()`	Removes focus from the rating.
`checkValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. If valid, `true` will be returned.
`reportValidity()`	Checks if the form control has any restraints and whether it satisfies them. If invalid, `false` will be returned and the `invalid` event will be dispatched. In addition, the problem will be reported to the user. If valid, `true` will be returned.
`stepDown()`	Decreases the rating's value by `step`. This is a programmatic change, so `input` and `change` events will not be emitted when this is called.
`stepUp()`	Increases the rating's value by `step`. This is a programmatic change, so `input` and `change` events will not be emitted when this is called.

Events Jump to heading

Rating dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`change`
`input`
`quiet-blur`	Emitted when the rating loses focus. This event does not bubble.
`quiet-change`	Emitted when the user commits changes to the rating's value.
`quiet-focus`	Emitted when the rating receives focus. This event does not bubble.
`quiet-input`	Emitted when the rating receives input.

CSS parts Jump to heading

Rating exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`label`	The element that contains the ratings's label.	`::part(label)`
`description`	The element that contains the rating's description.	`::part(description)`
`rating`	The element that wraps all of the rating's symbols.	`::part(rating)`
`symbol`	The container that holds the selected and unselected version of each symbol.	`::part(symbol)`

Custom States Jump to heading

Rating has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`disabled`	Applied when the rating is disabled.	`:state(disabled)`
`focused`	Applied when the rating has focus.	`:state(focused)`
`user-valid`	Applied when the rating is valid and the user has sufficiently interacted with it.	`:state(user-valid)`
`user-invalid`	Applied when the rating is invalid and the user has sufficiently interacted with it.	`:state(user-invalid)`

Rating

Examples Jump to heading #

Labels and descriptions Jump to heading #

Providing an initial value Jump to heading #

Changing the scale Jump to heading #

Fractional values Jump to heading #

Changing the size Jump to heading #

Using custom symbols Jump to heading #

Readonly ratings Jump to heading #

Disabling Jump to heading #

Validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #