---
title: Rating
description: An input that sets a value by choosing stars.
category: Form
status: beta
since: 0.3.4
tags: [rating, star, feedback]
syncStatus: reviewed
verified: true
---

## Usage

### Half Stars
With `precision="0.5"`, clicking the selected full star again turns it into a half star.

::TuffDemoWrapper{demo="RatingBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const score = ref(3.5)
  </script>

  <template>
    <TxRating v-model="score" :precision="0.5" show-text />
  </template>
---
::

### Custom Icons
`icon` sets every state; `filledIcon` / `emptyIcon` / `halfIcon` override one each. Built-in icons, Iconify classes, and emoji all work.

::TuffDemoWrapper{demo="RatingIconDemo" code-lang="vue"}
---
code: |
  <template>
    <TxRating v-model="diamond" icon="💎" show-text />
    <TxRating v-model="hearts" icon="i-carbon-favorite-filled" filled-color="#f43f5e" :precision="0.5" />
    <TxRating v-model="faces" filled-icon="😍" empty-icon="😶" :precision="0.5" />
  </template>
---
::

### Click Animation
A bounce, glow, and ripple play by default; `:animated="false"` turns them off.

::TuffDemoWrapper{demo="RatingAnimationDemo" code-lang="vue"}
---
code: |
  <template>
    <TxRating v-model="score" :precision="0.5" show-text />
    <TxRating v-model="still" :animated="false" show-text />
  </template>
---
::

### Custom Styles
Colors, `size`, and `gap` each have a prop; the `#text` slot rewrites the score text.

::TuffDemoWrapper{demo="RatingStyleDemo" code-lang="vue"}
---
code: |
  <template>
    <TxRating
      v-model="score"
      :size="30"
      :gap="8"
      filled-color="#f97316"
      empty-color="rgba(249, 115, 22, 0.2)"
      hover-color="#fb923c"
      text-color="#f97316"
      show-text
    />

    <TxRating v-model="score" readonly show-text>
      <template #text="{ value, max }">
        {{ value }} / {{ max }} readonly
      </template>
    </TxRating>
  </template>
---
::

### Best Practices

- Use `precision="0.5"` only when half steps mean something; use full stars for coarse satisfaction.
- Use `disabled` when input is unavailable and `readonly` to display a past score.
- Turn on `showText` or provide a `#text` slot when the exact value matters.
- If an icon set's states don't contrast clearly, use one shared `icon` and tell states apart by color.
- Turn off `animated` in dense forms and tables.

## API Reference

### Props
:::TuffPropsTable
---
rows:
  - name: modelValue
    type: number
    default: '0'
    description: The current score, bound with `v-model`.
  - name: maxStars
    type: number
    default: '5'
    description: Number of stars.
  - name: precision
    type: "number | 0.5"
    default: '1'
    description: Step size; `0.5` enables half stars, other values only set the score text's decimal places.
  - name: showText
    type: boolean
    default: 'false'
    description: Shows the score text after the stars.
  - name: disabled
    type: boolean
    default: 'false'
    description: Blocks rating and marks the root `aria-disabled`.
  - name: readonly
    type: boolean
    default: 'false'
    description: Displays the score only and marks the root `aria-readonly`.
  - name: icon
    type: "string | TxIconSource"
    default: '-'
    description: Icon shared by the filled and empty layers; state icons take precedence.
  - name: filledIcon
    type: "string | TxIconSource"
    default: 'star'
    description: Filled icon; falls back to `icon`, then `star`.
  - name: emptyIcon
    type: "string | TxIconSource"
    default: 'star'
    description: Empty icon; falls back to `icon`, then `star`.
  - name: halfIcon
    type: "string | TxIconSource"
    default: '-'
    description: Half-star icon; when omitted, the filled layer is clipped from the left.
  - name: filledColor
    type: string
    default: '#fbbf24'
    description: Color of filled icons.
  - name: emptyColor
    type: string
    default: '#d1d5db'
    description: Color of empty icons.
  - name: hoverColor
    type: string
    default: 'filledColor'
    description: Color of the filled layer on hover.
  - name: textColor
    type: string
    default: '#6b7280'
    description: Color of the score text.
  - name: size
    type: "number | string"
    default: '20px'
    description: Star icon size; numbers are treated as px.
  - name: gap
    type: "number | string"
    default: '2px'
    description: Gap between stars; numbers are treated as px.
  - name: animated
    type: boolean
    default: 'true'
    description: Plays the bounce and ripple after a selection.
  - name: starLabel
    type: "(star: number) => string"
    default: '-'
    description: Accessible label for each star; defaults to English `Rate N star(s)`.
---
:::

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:modelValue` | `(value: number)` | Fires with the new score after an interactive star is clicked. |
| `change` | `(value: number)` | Fires together with `update:modelValue`. |

### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `text` | `{ value: number, max: number }` | Replaces the default `value / max` text when `showText` is on. |

## Overview

- The star row renders as `role="radiogroup"`, and each star is a `role="radio"` button.
- Keyboard: the row is a single tab stop; ArrowRight/ArrowUp select the next star and ArrowLeft/ArrowDown the previous, without wrapping; Home/End select the first and last.
- `disabled` and `readonly` both block updates; the score still shows.

## Technologies

- Source: `packages/tuffex/packages/components/src/rating/`; exports the `RatingProps`, `RatingEmits`, and `RatingIcon` types.

<TuffDocSourceLink />