Kappa / Rating

Mesh qualityHow useful was this generated mesh?

4 / 5

Rating

<script setup>
import { ref } from "vue";
import { Rating } from "@dicehub/kappa/components/rating";

const rating = ref(3);
</script>

<template>
  <Rating.Root v-model="rating" name="result-quality">
    <Rating.Label>Result quality</Rating.Label>
    <Rating.Control />
  </Rating.Root>
</template>

Installation

Rating uses Ark UI Rating Group behavior while keeping the public Kappa name short. The default control renders its items and hidden form input automatically.

Barrel

import { Rating } from "@dicehub/kappa";

Granular

import { Rating } from "@dicehub/kappa/components/rating";

Usage

Provide a visible label or an accessible name. Use v-model for controlled values and default-value for local state.

<script setup>
import { ref } from "vue";
import { Rating } from "@dicehub/kappa/components/rating";

const rating = ref(3);
</script>

<template>
  <Rating.Root v-model="rating" name="result-quality">
    <Rating.Label>Result quality</Rating.Label>
    <Rating.Control />
  </Rating.Root>
</template>

Composition

Typical part hierarchy

Rating.Root
├── Rating.Label
├── Rating.Control
│   └── Rating.Item × count (automatic)
├── HiddenInput (automatic)
└── Rating.Context (optional)

<Rating.Root>
  <Rating.Label />
  <Rating.Control>
    <!-- Rating.Item parts render automatically. -->
  </Rating.Control>
  <Rating.Context />
</Rating.Root>

Control renders the default star items from count.
Use the scoped Control slot only when the rating needs a different icon.
The native form input is automatic. Do not add a second hidden input.

Examples

Sizes

Use small, base, or large geometry without changing rating behavior.

Base

<Rating.Root :default-value="3" size="sm" read-only>
  <Rating.Label>Small</Rating.Label>
  <Rating.Control />
</Rating.Root>

<Rating.Root :default-value="3" size="base" read-only>
  <Rating.Label>Base</Rating.Label>
  <Rating.Control />
</Rating.Root>

<Rating.Root :default-value="3" size="lg" read-only>
  <Rating.Label>Large</Rating.Label>
  <Rating.Control />
</Rating.Root>

Half Values

Enable half-step selection when whole values are not precise enough.

Solver rating

Selected: 3.5

<script setup>
import { ref } from "vue";
import { Rating } from "@dicehub/kappa/components/rating";

const rating = ref(3.5);
</script>

<template>
  <Rating.Root v-model="rating" allow-half name="solver-rating">
    <Rating.Label>Solver rating</Rating.Label>
    <Rating.Control />
  </Rating.Root>
</template>

Controlled

Use v-model when application state owns the selected value.

Review rating

2 of 5

<script setup>
import { ref } from "vue";
import { Rating } from "@dicehub/kappa/components/rating";

const rating = ref(2);
</script>

<template>
  <Rating.Root v-model="rating" name="review-rating">
    <Rating.Label>Review rating</Rating.Label>
    <Rating.Control />
  </Rating.Root>
  <output>{{ rating }} of 5</output>
</template>

Custom Icons

Replace the default star by rendering explicit Item parts from the Control slot.

Result confidence

<script setup>
import { Rating } from "@dicehub/kappa/components/rating";
import { Hexagon } from "@lucide/vue";
</script>

<template>
  <Rating.Root :default-value="4" name="confidence">
    <Rating.Label>Result confidence</Rating.Label>
    <Rating.Control v-slot="{ items }">
      <Rating.Item v-for="item in items" :key="item" :index="item">
        <Hexagon aria-hidden="true" />
      </Rating.Item>
    </Rating.Control>
  </Rating.Root>
</template>

States

Disabled, read-only, and invalid states remain visually distinct.

Disabled

Read-only

Required rating

Select a rating.

<Rating.Root :default-value="3" disabled>
  <Rating.Label>Disabled</Rating.Label>
  <Rating.Control />
</Rating.Root>

<Rating.Root :default-value="4" read-only>
  <Rating.Label>Read-only</Rating.Label>
  <Rating.Control />
</Rating.Root>

<Rating.Root invalid required name="required-rating" aria-describedby="rating-error">
  <Rating.Label>Required rating</Rating.Label>
  <Rating.Control />
</Rating.Root>
<p id="rating-error">Select a rating.</p>

Accessibility

Arrow keys change the active value. Home and End move to the minimum or maximum value.
A visible label is preferred. Otherwise, provide aria-label or aria-labelledby.
Disabled ratings cannot receive input. Read-only ratings expose their value without changing it.
Custom icons must be decorative. Ark UI supplies each item's accessible name.
Invalid ratings need nearby error text connected with aria-describedby.

See the official Ark UI Rating Group documentation for the complete behavior contract.

API Reference

Rating.Root

Prop	Type	Default	Description
`modelValue`	`number`	`—`	Controlled rating value; supports v-model.
`defaultValue`	`number`	`0`	Initial value for uncontrolled use.
`count`	`number`	`5`	Total number of rating items.
`allowHalf`	`boolean`	`false`	Allows half-step values.
`size`	`"sm" \| "base" \| "lg"`	`"base"`	Controls item and icon geometry.
`disabled`	`boolean`	`false`	Prevents interaction and form changes.
`readOnly`	`boolean`	`false`	Preserves the value without allowing changes.
`invalid`	`boolean`	`false`	Applies invalid styling and aria-invalid.
`name / form / required`	`form props`	`—`	Connects the generated hidden input to native forms.

Parts

Part	Element	Description
`Rating.Root / RootProvider`	`div`	Owns rating value, hover, form, and direction state.
`Rating.Label`	`label`	Visible accessible label for the rating.
`Rating.Control`	`div`	Renders all default items or exposes the item list through its slot.
`Rating.Item`	`span`	One selectable value. It renders Kappa's star unless replaced by a slot.
`Rating.Context / ItemContext`	`none`	Exposes root or item state to custom compositions.

Events

Event	Payload	Description
`update:modelValue`	`number`	The controlled value changed.
`valueChange`	`RatingValueChangeDetails`	A rating value was selected.
`hoverChange`	`RatingHoverChangeDetails`	The preview value under the pointer changed.

Exports

Export	Description
`Rating / RatingRoot`	Compound root and named root export.
`RatingLabel / Control / Item`	Named exports for the visible rating parts.
`RatingProps / Rating*Props`	Public root and part contracts.
`RATING_SIZES / RATING_DEFAULT_SIZE`	Supported sizes and default size.
`useRating / useRatingContext / useRatingItemContext`	Ark UI hooks under Kappa Rating names.
`ratingAnatomy`	Ark UI rating-group anatomy under the Kappa name.