Rating

VRating lets the reader give a rating out of a few icons. It is a group of native radios, so the arrow keys, form submission and required work as in any form.

Usage

vue

<script setup lang="ts">
import { ref } from 'vue'
import { VRating } from 'vectis-ui'

const rating = ref<number | null>(3)
</script>

<template>
  <VRating v-model="rating" label="Quality" hint="Your overall impression of the product." />
</template>

Examples

Clearable

clearable lets the rating go back to null: click the current value again, or reach "No rating" with the arrow keys.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { VRating, VTypography } from 'vectis-ui'

const rating = ref<number | null>(4)
</script>

<template>
  <div class="demo">
    <VRating v-model="rating" label="Delivery" clearable />
    <VTypography variant="body-sm" tone="muted">Value: {{ rating ?? 'null' }}</VTypography>
  </div>
</template>

<style scoped>
.demo {
  display: grid;
  gap: var(--vectis-space-3);
}
</style>

Read-only

readonly shows the value as a single image named after it, such as "3.7 out of 5". A fractional value fills part of an icon.

vue

3.7 · 128 reviews

<script setup lang="ts">
import { VRating, VTypography } from 'vectis-ui'
</script>

<template>
  <div class="summary">
    <VRating
      :model-value="3.7"
      readonly
      size="sm"
      tone="warning"
      label="Average rating"
      hide-label
    />
    <VTypography variant="body-sm" tone="muted">3.7 · 128 reviews</VTypography>
  </div>
</template>

<style scoped>
.summary {
  display: flex;
  align-items: center;
  gap: var(--vectis-space-2);
}
</style>

Sizes

size sets the icons to 20, 24 or 32 pixels.

vue

<script setup lang="ts">
import { VRating } from 'vectis-ui'
</script>

<template>
  <div class="sizes">
    <VRating :model-value="4" size="sm" label="Small" />
    <VRating :model-value="4" label="Medium" />
    <VRating :model-value="4" size="lg" label="Large" />
  </div>
</template>

<style scoped>
.sizes {
  display: grid;
  gap: var(--vectis-space-4);
}
</style>

Tones and icons

tone colours the filled icons, and color replaces it with a colour of your own. icon replaces the star with any icon; the empty ones are drawn in outline and the filled ones with its filled form.

vue

<script setup lang="ts">
import { VRating } from 'vectis-ui'
</script>

<template>
  <div class="tones">
    <VRating :model-value="4" label="Accent" />
    <VRating :model-value="4" tone="warning" label="Warning" />
    <VRating :model-value="4" tone="neutral" label="Neutral" />
    <VRating :model-value="4" color="#e91e63" label="Custom colour" />
  </div>
</template>

<style scoped>
.tones {
  display: grid;
  gap: var(--vectis-space-4);
}
</style>

Validation

VRating follows the field model: error replaces the hint and is announced, and required adds an asterisk and makes the browser require a choice.

vue

<script setup lang="ts">
import { computed, ref } from 'vue'
import { VRating } from 'vectis-ui'

const rating = ref<number | null>(null)
const error = computed(() => (rating.value === null ? 'Choose a rating.' : undefined))
</script>

<template>
  <VRating v-model="rating" label="Quality" :error="error" required name="quality" />
</template>

API

Props

Prop	Type	Default
`max`	`number`	`5`
Number of icons, and highest value.
`label`	`string`	none
Legend of the group. Defaults to the library dictionary as an accessible name.
`hideLabel`	`boolean`	`false`
Hides the label visually while keeping it as the group name.
`hint`	`string`	none
Help text under the icons.
`error`	`string`	none
Error message replacing the hint. Announced when it appears or changes.
`required`	`boolean`	`false`
Requires a rating in a form and adds an asterisk.
`name`	`string`	none
Field name in form submissions.
`clearable`	`boolean`	`false`
Lets the rating go back to none, by clicking the current value or with a "No rating" choice.
`readonly`	`boolean`	`false`
Shows the value as a single image. A fractional value fills part of an icon.
`disabled`	`boolean`	`false`
Disables the whole group.
`size`	`RatingSize'sm' \| 'md' \| 'lg'`	`'md'`
Icon size.
`tone`	`RatingTone'accent' \| 'warning' \| 'danger' \| 'success' \| 'neutral'`	`'accent'`
Colour of the filled icons.
`color`	`string`	none
Custom colour of the filled icons (hex, CSS name or `oklch()`), replacing the tone. Check its contrast.
`icon`	`IconSource`	`star`
Icon replacing the star.
`v-model`	`number \| null`	`null`
Rating from 1 to `max`, or `null`. May be fractional when read-only.

Types

Types used in the API tables. Import exported types from vectis-ui.

export interface BuiltinIcon {
  name: string
  paths: readonly [string] | readonly [string, string]
}

export type IconRender =
  | { path: string; viewBox?: string }
  | { component: Component; props?: Record<string, unknown> }
  | { src: string }
  | { text: string; class?: string }
  | { class: string }

export type IconSource = string | BuiltinIcon | IconRender

CSS variables

Token	Value
`--vectis-control-size-rating-sm`	`1.25rem`
`--vectis-control-size-rating-md`	`1.5rem`
`--vectis-control-size-rating-lg`	`2rem`