Rating `<mv-rating>`

Avaliação por estrelas, para exibição (precisão decimal real: 4,3 preenche 30% da 5ª estrela, número de avaliações como link) ou como entrada integrada a formulários: meias estrelas, prévia ao passar o mouse, legendas como “Very good”, suporte completo a teclado, limpeza, obrigatório; variante compacta ★ 4,8 (2.413).

Categoria	Formulários
Tipo	Web Component (`<mv-rating>`)
Status	estável
Keywords	rating, stars, étoiles, note, avis, review, half-star, form-associated, e-commerce

When to use

A product card or listing shows an average rating with decimal precision and a review count
A review form asks users to rate from one to five stars, optionally with half stars
A compact star, score and count summary must fit in a tight row

Avoid when

A full reviews section with histogram, filters and review cards is needed → use Review instead
The score is a satisfaction or NPS scale from 0 to 10 where stars would be misleading → use Radio instead

Instalação

node scripts/add.mjs rating --out ./src/marvelous

Agente de IA com o servidor MCP do Marvelous UI: install_components({ slugs: ["rating"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Arquivos copiados (dependências incluídas): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/form.js, core/motion.js, components/rating/rating.js, components/rating/rating.css.

Uso

Marcação de referência, para usar como ponto de partida e personalizar com atributos, data-* e variáveis CSS:

<div id="rating-demo" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,19rem),1fr));gap:1.5rem;width:min(100%,48rem);margin-inline:auto;font-size:.875rem">
  <style>
    #rating-demo .panel { display:grid; gap:1rem; align-content:start; padding:1.25rem; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface) }
    #rating-demo .cap { margin:0; font-size:.75rem; font-weight:500; color:var(--mv-fg-muted) }
    #rating-demo .row { display:flex; align-items:center; justify-content:space-between; gap:1rem }
  </style>

  <div class="panel">
    <p class="cap">Display (read-only)</p>
    <div style="display:grid;gap:.375rem">
      <strong style="font-size:1rem">Merino crew-neck sweater</strong>
      <mv-rating readonly value="4.6" count="128" href="#reviews" show-value></mv-rating>
    </div>
    <div class="row"><span>Decimal precision</span><mv-rating readonly value="3.7" show-value data-size="sm"></mv-rating></div>
    <div class="row"><span>Compact</span><mv-rating readonly value="4.8" count="2413" data-variant="compact" data-size="sm"></mv-rating></div>
    <div class="row"><span>Large</span><mv-rating readonly value="4.5" data-size="lg"></mv-rating></div>
    <div class="row"><span>Out of 10</span><mv-rating readonly value="8.5" max="10" show-value data-size="sm" style="--mv-rating-color:var(--mv-accent)"></mv-rating></div>
  </div>

  <form class="panel" id="rating-demo-form" novalidate>
    <p class="cap">Input (form)</p>
    <div style="display:grid;gap:.5rem">
      <label for="rating-demo-note" style="font-weight:500">Your rating <span style="color:var(--mv-danger)" aria-hidden="true">*</span></label>
      <mv-rating id="rating-demo-note" name="note" required clearable placeholder="Pick a rating" data-size="lg" aria-describedby="rating-demo-help"></mv-rating>
      <small id="rating-demo-help" style="color:var(--mv-fg-muted)">Hover and click, or use the arrow keys (or type 1-5).</small>
    </div>
    <div style="display:grid;gap:.5rem">
      <label for="rating-demo-half" style="font-weight:500">Comfort (half stars)</label>
      <mv-rating id="rating-demo-half" name="comfort" precision="0.5" value="3.5" captions="Very uncomfortable,Uncomfortable,Okay,Comfortable,Very comfortable"></mv-rating>
    </div>
    <div style="display:grid;gap:.5rem">
      <span style="font-weight:500">Disabled</span>
      <mv-rating value="4" disabled label="Quality"></mv-rating>
    </div>
    <div style="display:flex;gap:.5rem;align-items:center">
      <button class="mv-button" type="submit">Post review</button>
      <button class="mv-button" type="reset" data-variant="ghost">Reset</button>
    </div>
    <output id="rating-demo-out" style="min-height:1.25rem;font-size:.8125rem;color:var(--mv-fg-muted)" aria-live="polite"></output>
  </form>
</div>
<script type="module">
  const form = document.getElementById("rating-demo-form");
  const out = document.getElementById("rating-demo-out");
  const note = form.querySelector("#rating-demo-note");
  form.addEventListener("submit", (e) => {
    e.preventDefault();
    if (!form.checkValidity()) {
      note.setAttribute("invalid", "");
      out.style.color = "var(--mv-danger)";
      out.textContent = "Pick a rating before posting.";
      note.focus();
      return;
    }
    out.style.color = "";
    out.textContent = `Submitted: ${new URLSearchParams(new FormData(form)).toString()}`;
  });
  note.addEventListener("mv-change", (e) => {
    note.removeAttribute("invalid");
    out.style.color = "";
    out.textContent = e.detail.value ? `Rating: ${e.detail.value}/5 (${e.detail.label})` : "Rating cleared";
  });
  form.addEventListener("reset", () => { note.removeAttribute("invalid"); out.textContent = ""; });
</script>

API

Attributes

Name	Tipo	Default	Description
`value`	number	`0`	Rating (0 = none). Observed: a framework can drive it via the attribute.
`max`	number	`5`	Number of stars.
`precision`	1 \| 0.5	`1`	Input step (0.5 = half stars).
`readonly`	boolean		Display mode: role=img, unrounded value.
`clearable`	boolean		Clicking the current rating again clears it.
`name / required / disabled`	string / boolean		Form: submitted value “4.5”, valueMissing when required and empty.
`count`	number		Review count shown (“128 reviews”).
`href`	string		Turns the review count into a link (anchor to the reviews section).
`show-value`	boolean		Shows the numeric rating (“4.6”).
`label`	string	`Rating`	Accessible name (otherwise `<label for>`).
`captions`	string	`Poor,Fair,Good,Very good,Excellent`	Per-star captions, shown during input and read in aria-valuetext.
`locale`	string	`en-US`	Number formatting.
`data-size`	sm \| lg \| xl		Star size.
`data-variant`	compact		One star + rating + (count).
`invalid`	boolean		Error style.

Properties

Name	Tipo	Description
`value`	number	Current rating.
`form / validity / labels`		Via ElementInternals.

Methods

Name	Description
`focus()`	Focuses the star slider.
`checkValidity() / reportValidity()`	Native validation.

Events

Name	Description
`mv-change`	User change. detail: { value, label }.

CSS classes

Name	Description
`mv-rating-stars / -star / -value / -text / -count`	Generated parts; --_fill (0…1) on each star.

CSS variables

Name	Default	Description
`--mv-rating-size`	`1.125rem`	Size of one star.
`--mv-rating-color`	`var(--mv-warning)`	Filled stars.
`--mv-rating-empty-color`	`gray`	Empty stars.

Accessibility

Display: role=img with aria-label “Rating: 4.6 out of 5 (128 reviews)”. Input: APG “Rating slider” pattern, a single focusable role=slider element, aria-valuenow / aria-valuetext (“4 stars out of 5, Very good” or “No rating”). Arrow keys ±precision (reversed in RTL), Page Up/Down ±1, Home/End, digits 0-9 directly, Backspace/Delete clears. Hover is only a preview; focus stays visible. Name via <label for>, label or aria-label.