Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Rating

A star rating built on native radio inputs, with half steps, a read-only display, and form submission.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add rating

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Rating from './components/ui/rating/Rating.vue'

const score = ref(3)
const messages = {
  none: 'No rating',
  value: (value: number, max: number) => `${value} of ${max} stars`,
}
</script>

<template>
  <Rating v-model="score" name="score" label="Product quality" :messages="messages" />
</template>

Bind a number with v-model, name the group with label, and pass translated messages. Arrow keys, Home, and End work out of the box. Hover previews fill newly reached stars in a short stagger and lift them slightly; selecting a rating gives the committed star a restrained pulse. These effects stop under reduced motion, and hover never commits a value.

When to use it

Feedback forms

Collect a score from one to five stars in a review or survey.

Read-only scores

Show an average rating in a list or product card.

More examples

Half steps

Add allow-half to add a radio for each half star.

Half steps
<script setup lang="ts">
import { ref } from 'vue'
import Rating from './components/ui/rating/Rating.vue'

const score = ref(2.5)
const messages = {
  none: 'No rating',
  value: (value: number, max: number) => `${value} of ${max} stars`,
}
</script>

<template>
  <div class="flex items-center gap-3">
    <Rating v-model="score" allow-half size="lg" label="Service" :messages="messages" />
    <span class="text-sm tabular-nums text-muted-foreground">{{ score }}</span>
  </div>
</template>

Read-only display

Use readonly to show a value with no controls.

Read-only display
<script setup lang="ts">
import Rating from './components/ui/rating/Rating.vue'

const messages = {
  none: 'No rating',
  value: (value: number, max: number) => `${value} of ${max} stars`,
}
</script>

<template>
  <div class="flex items-center gap-2">
    <Rating
      :model-value="4.5"
      allow-half
      readonly
      size="sm"
      label="Average rating"
      :messages="messages"
    />
    <span class="text-sm text-muted-foreground">4.5 (128 reviews)</span>
  </div>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Rating

Complete API for Rating
NameType or signatureDefaultWhat it does
maxpropnumber | undefined5Number of stars.
allowHalfpropboolean | undefinedNot setAllow 0.5 steps.
readonlypropboolean | undefinedNot setShow the value without any control. Exposes it as an image with a text value.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
namepropstring | undefinedNot setForm field name. Without one, the radios are grouped by a generated name that is still submitted.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
labelpropstringRequiredAccessible name of the group.
messagespropRatingMessagesRequiredRequired radio names and read-only summary text.
modelValuemodelnumber | undefined0Current value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: number]—Requests a new model value from the parent.
iconslot((props: { filled: boolean; half: boolean; }) => unknown) | undefinedOptionalContent for the icon area of Rating.
valueexposednumber—Access value from a component template ref.
Public type definitions
Public types
// packages/frameworks/vue/components/rating/types.ts
// ------- IMPORTS -------

import type { RatingMessages } from '@getweini/vue/primitives/rating'

// ------- TYPES -------

export type { RatingMessages }

export interface RatingProps {
  /** Number of stars. */
  max?: number
  /** Allow 0.5 steps. */
  allowHalf?: boolean
  /** Show the value without any control. Exposes it as an image with a text value. */
  readonly?: boolean
  disabled?: boolean
  /** Form field name. Without one, the radios are grouped by a generated name that is still submitted. */
  name?: string
  form?: string
  size?: 'sm' | 'md' | 'lg'
  /** Accessible name of the group. */
  label: string
  /** Required radio names and read-only summary text. */
  messages: RatingMessages
}


// packages/frameworks/vue/dist/vue/primitives/rating/index.d.ts
import { type ComponentPublicInstance, type Ref } from 'vue';
/** Application-owned copy for radio names and the read-only summary. */
export interface RatingMessages {
    /** Name of the visually hidden radio that sets the rating to 0. */
    none: string;
    /** Name for a value, for example `${value} of ${max} stars`. */
    value: (value: number, max: number) => string;
}
export interface RatingBehaviorOptions {
    max: () => number;
    allowHalf: () => boolean;
    readonly: () => boolean;
    disabled: () => boolean;
    name: () => string | undefined;
    messages: () => RatingMessages;
}
export interface RatingStar {
    index: number;
    /** Fill of the committed-or-previewed value: 0, 0.5, or 1. */
    fill: 0 | 0.5 | 1;
    /** The preview fills more of this star than the committed value does. */
    previewOnly: boolean;
    /** Value selected by the full-star radio. */
    value: number;
    /** Value selected by the half-star radio when half steps are enabled. */
    halfValue: number;
}
/** Models, hover preview, Home/End, commit feedback, and names for Rating. */
export declare function useRating(rawModel: Ref<number>, options: RatingBehaviorOptions): {
    selection: import("vue").WritableComputedRef<number, number>;
    value: import("vue").ComputedRef<number>;
    max: import("vue").ComputedRef<number>;
    stars: import("vue").ComputedRef<RatingStar[]>;
    preview: Ref<number | null, number | null>;
    popIndex: Ref<number | null, number | null>;
    interactive: import("vue").ComputedRef<boolean>;
    radioName: import("vue").ComputedRef<string>;
    labelId: string;
    valueId: string;
    nameFor: (radioValue: number) => string;
    setRoot: (element: Element | ComponentPublicInstance | null) => void;
    handlePointerEnter: (radioValue: number, event: PointerEvent) => void;
    handlePointerLeave: () => void;
    handleKeydown: (event: KeyboardEvent) => void;
};

Implementation notes

  • The component renders real radio inputs, so name and form submit the value natively.
  • Hover previews a value for mouse pointers only and never changes the model. Touch and keyboard commit directly.
  • Use #icon to draw other shapes; it receives filled and half.

Accessibility and localization

  • label names the radiogroup and messages names each radio and the read-only summary, so translate both.
  • A hidden "none" radio lets keyboard users return to 0; Home and End jump to the ends.
  • readonly is exposed as an image with a text value instead of disabled controls.
  • A named read-only value submits through a hidden field; when disabled, it is omitted from form submission.
  • Half-star targets remain at least 24×24px at every size.

Source contract and editing guidance