Feedback forms
Collect a score from one to five stars in a review or survey.
Components / Forms
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.
bunx --bun @getweini/cli@latest add ratingImport 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.
<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.
Collect a score from one to five stars in a review or survey.
Show an average rating in a list or product card.
Add allow-half to add a radio for each half star.
<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>Use readonly to show a value with no controls.
<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>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.
| Name | Type or signature | Default | What it does |
|---|---|---|---|
maxprop | number | undefined | 5 | Number of stars. |
allowHalfprop | boolean | undefined | Not set | Allow 0.5 steps. |
readonlyprop | boolean | undefined | Not set | Show the value without any control. Exposes it as an image with a text value. |
disabledprop | boolean | undefined | Not set | Prevent interaction and show the disabled state. |
nameprop | string | undefined | Not set | Form field name. Without one, the radios are grouped by a generated name that is still submitted. |
formprop | string | undefined | Not set | Associate 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. |
labelprop | string | Required | Accessible name of the group. |
messagesprop | RatingMessages | Required | Required radio names and read-only summary text. |
modelValuemodel | number | undefined | 0 | Current 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) | undefined | Optional | Content for the icon area of Rating. |
valueexposed | number | — | Access value from a component template ref. |
// 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;
};name and form submit the value natively.#icon to draw other shapes; it receives filled and half.label names the radiogroup and messages names each radio and the read-only summary, so translate both.readonly is exposed as an image with a text value instead of disabled controls.disabled, it is omitted from form submission.