createRating

Bounded number with discrete items. Give it a size, get items to iterate with full/half/empty state. Half-step support for 0.5 increments.

Copy Markdown

Preview Intermediate Jun 29, 2026

Usage

import { createRating } from '@vuetify/v0'
import { shallowRef } from 'vue'

// Basic — standalone
const rating = createRating({ size: 5 })
rating.select(3)
rating.items.value
// [
//   { value: 1, state: 'full' },
//   { value: 2, state: 'full' },
//   { value: 3, state: 'full' },
//   { value: 4, state: 'empty' },
//   { value: 5, state: 'empty' },
// ]

// With half-step support
const half = createRating({ size: 5, half: true })
half.select(2.5)
half.items.value[2].state // 'half'

// With v-model (pass a ref)
const value = shallowRef(0)
const bound = createRating({ value, size: 5 })
bound.select(4)
value.value // 4

Context / DI

Use createRatingContext to share a rating instance across a component tree:

import { createRatingContext } from '@vuetify/v0'

export const [useProductRating, provideProductRating, productRating] =
  createRatingContext({ namespace: 'my:rating', max: 5 })

// In parent component
provideProductRating()

// In child component
const rating = useProductRating()
rating.select(4)

Reactivity

Property	Type	Reactive	Description
`value`	`WritableComputedRef<number>`	Yes	Current rating, clamped 0–size
`size`	`number`	Getter	Total items
`half`	`boolean`	Getter	Half-step enabled
`items`	`ComputedRef<RatingItem[]>`	Yes	Items with `full`/`half`/`empty` state
`isFirst`	`Readonly<Ref<boolean>>`	Yes	Value is 0
`isLast`	`Readonly<Ref<boolean>>`	Yes	Value equals size
`select(v)`	`(value: number) => void`	—	Set rating
`next()`	`() => void`	—	Increment by step
`prev()`	`() => void`	—	Decrement by step
`first()`	`() => void`	—	Set to 0
`last()`	`() => void`	—	Set to size

A half-star review widget built directly on createRating — no Rating component. It demonstrates the three things the composable gives you for free: an items array whose state is already resolved to full, half, or empty; half-step values via half: true (so select(2.5) is valid and the mid-point star renders half-filled); and isFirst / isLast boundary guards that disable the step buttons at 0 and 5. The component reads state per star and clips a filled glyph over an outline to draw the half, while select and the next / prev steppers commit the value.

The interesting detail is how hover preview stays honest without any hand-rolled math. The composable holds two createRating instances: one for the committed value, and a second whose value is bound to a hover ref. While the pointer is over the stars, display reads the preview instance’s items; on mouseleave it falls back to the committed instance’s items. Both renderings come straight from createRating, so the full/half/empty logic is never duplicated. DOM events (mouseenter, click, mouseleave) live in the component; the value math lives in the composable, keeping the composable headless.

Reach for createRating over a plain reactive number whenever you want per-item state, half steps, and clamped boundaries handed to you. It has no DOM dependencies, so the same instance backs an editable widget, a compact read-only display, or a server-submitted score. For the fully accessible spin-button treatment, see the Rating component; for related bounded-value math, see createNumeric and createSlider.

File	Role
`useStarRating.ts`	Owns two createRating instances (committed + hover preview), exposes display, label, and submit/reset
`StarRating.vue`	Renders the half-clippable stars and step buttons; binds hover and click events
`star-rating.vue`	Entry point — creates the composable, wires the view, and shows the submitted score