---
name: n-rate
description: A rating component for collecting user feedback with customizable icons, colors, and half-star support in Naive UI. Ideal for product reviews, feedback forms, and rating systems.
metadata:
  author: jiaiyan
  version: 1.0.0
---

# n-rate Component

The `n-rate` component allows users to provide ratings, typically represented as stars or custom icons. It supports half-star ratings, custom colors, and various sizes.

## When to Use

Use `n-rate` when you need to:

- **Product Reviews**: Allow users to rate products or services
- **Feedback Collection**: Gather user satisfaction ratings
- **Content Rating**: Rate articles, videos, or other content
- **Skill Assessment**: Display or collect skill level ratings
- **Quick Evaluation**: Provide a simple, intuitive rating interface

## Basic Usage

### Basic Rate

A simple 5-star rating component.

```vue
<template>
  <n-rate v-model:value="rating" />
  <p>Rating: {{ rating }}</p>
</template>

<script setup>
import { ref } from 'vue'

const rating = ref(0)
</script>
```

### Different Sizes

Rate supports `small`, `medium`, `large` sizes, or custom numeric sizes.

```vue
<template>
  <n-space align="center">
    <n-rate size="small" v-model:value="small" />
    <n-rate size="medium" v-model:value="medium" />
    <n-rate size="large" v-model:value="large" />
    <n-rate :size="30" v-model:value="custom" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const small = ref(3)
const medium = ref(3)
const large = ref(3)
const custom = ref(3)
</script>
```

### Custom Color

Customize the color of active icons.

```vue
<template>
  <n-space vertical>
    <n-rate color="#4fb233" v-model:value="rating1" />
    <n-rate color="#f0a020" v-model:value="rating2" />
    <n-rate color="rgb(255, 0, 100)" v-model:value="rating3" />
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const rating1 = ref(4)
const rating2 = ref(3)
const rating3 = ref(5)
</script>
```

### Custom Icon

Use custom icons via the default slot.

```vue
<template>
  <n-rate v-model:value="rating">
    <template #default>
      <n-icon size="20">
        <CashIcon />
      </n-icon>
    </template>
  </n-rate>
</template>

<script setup>
import { ref } from 'vue'
import { CashOutline as CashIcon } from '@vicons/ionicons5'

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

### Half Star Rating

Enable half-star precision with `allow-half`.

```vue
<template>
  <n-rate allow-half v-model:value="rating" />
  <p>Rating: {{ rating }}</p>
</template>

<script setup>
import { ref } from 'vue'

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

### Readonly Mode

Display rating without user interaction.

```vue
<template>
  <n-space vertical>
    <n-rate readonly :value="3" />
    <n-rate readonly :value="4.5" allow-half />
    <n-rate readonly :value="2" color="#ff6b6b" />
  </n-space>
</template>
```

### Clearable

Allow users to clear the rating by clicking on the current value.

```vue
<template>
  <n-rate clearable allow-half v-model:value="rating" @clear="handleClear" />
  <p>Rating: {{ rating }}</p>
</template>

<script setup>
import { ref } from 'vue'

const rating = ref(3.5)

const handleClear = () => {
  console.log('Rating cleared')
}
</script>
```

### Custom Count

Set a custom maximum rating value.

```vue
<template>
  <n-rate :count="10" v-model:value="rating" />
  <p>Rating: {{ rating }} / 10</p>
</template>

<script setup>
import { ref } from 'vue'

const rating = ref(7)
</script>
```

## API Reference

### n-rate Props

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `allow-half` | `boolean` | `false` | Allow activating half of the icon |
| `clearable` | `boolean` | `false` | Whether the rate is clearable. Clicking on current value resets to `null` |
| `color` | `string` | `undefined` | Activated icon color. Supports `#FFF`, `#FFFFFF`, `yellow`, `rgb(0, 0, 0)` formats |
| `count` | `number` | `5` | Number of icons (maximum rating) |
| `default-value` | `number \| null` | `null` | Default value of activated icons |
| `readonly` | `boolean` | `false` | Readonly state |
| `size` | `'small' \| 'medium' \| 'large' \| number` | `'medium'` | Icon size |
| `value` | `number \| null` | `undefined` | Value of activated icons (controlled mode) |

### Events

| Name | Parameters | Description |
|------|------------|-------------|
| `on-clear` | `() => void` | Callback when value is cleared |
| `on-update:value` | `(value: number) => void` | Callback when the value (rating) changes |

### Slots

| Name | Parameters | Description |
|------|------------|-------------|
| `default` | `(info: { index: number })` | Custom icon for the rating. `index` is the position (0-based) |

## Common Patterns

### Rate in Form

```vue
<template>
  <n-form ref="formRef" :model="formData" :rules="rules">
    <n-form-item label="Overall Rating" path="rating">
      <n-rate allow-half clearable v-model:value="formData.rating" />
      <span style="margin-left: 12px">{{ formData.rating || 0 }} / 5</span>
    </n-form-item>
    <n-form-item label="Service Quality" path="serviceRating">
      <n-rate v-model:value="formData.serviceRating" />
    </n-form-item>
    <n-form-item>
      <n-button type="primary" @click="handleSubmit">Submit Review</n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref } from 'vue'

const formData = ref({
  rating: null,
  serviceRating: 0
})

const rules = {
  rating: {
    required: true,
    type: 'number',
    min: 1,
    message: 'Please provide a rating',
    trigger: 'change'
  }
}

const handleSubmit = () => {
  console.log('Review submitted:', formData.value)
}
</script>
```

### Display Rating with Text

```vue
<template>
  <n-space align="center">
    <n-rate readonly :value="productRating" allow-half />
    <span>{{ productRating.toFixed(1) }}</span>
    <span style="color: #999">({{ reviewCount }} reviews)</span>
  </n-space>
</template>

<script setup>
const productRating = 4.5
const reviewCount = 128
</script>
```

### Emoji Rating

```vue
<template>
  <n-rate :count="5" v-model:value="emojiRating">
    <template #default="{ index }">
      <span style="font-size: 24px">{{ getEmoji(index) }}</span>
    </template>
  </n-rate>
  <p>Selected: {{ getEmojiLabel(emojiRating) }}</p>
</template>

<script setup>
import { ref } from 'vue'

const emojiRating = ref(3)

const emojis = ['😠', '😕', '😐', '😊', '😄']
const labels = ['Very Bad', 'Bad', 'Okay', 'Good', 'Excellent']

const getEmoji = (index) => emojis[index] || '😐'
const getEmojiLabel = (value) => labels[Math.floor(value) - 1] || 'Not rated'
</script>
```

### Rating with Feedback

```vue
<template>
  <n-space vertical>
    <n-rate v-model:value="rating" @update:value="handleRatingChange" />
    <n-tag v-if="feedbackText" :type="feedbackType">
      {{ feedbackText }}
    </n-tag>
  </n-space>
</template>

<script setup>
import { ref, computed } from 'vue'

const rating = ref(0)

const feedbackMap = {
  1: { text: 'Very Dissatisfied', type: 'error' },
  2: { text: 'Dissatisfied', type: 'warning' },
  3: { text: 'Neutral', type: 'default' },
  4: { text: 'Satisfied', type: 'success' },
  5: { text: 'Very Satisfied', type: 'success' }
}

const feedbackText = computed(() => feedbackMap[rating.value]?.text || '')
const feedbackType = computed(() => feedbackMap[rating.value]?.type || 'default')

const handleRatingChange = (value) => {
  console.log('Rating changed to:', value)
}
</script>
```

## Best Practices

### 1. Use Half-Star for Precise Ratings

Enable `allow-half` when users need to provide more precise ratings:

```vue
<template>
  <n-rate allow-half v-model:value="rating" />
</template>
```

### 2. Provide Clear Feedback

Show the current rating value alongside the component:

```vue
<template>
  <n-space align="center">
    <n-rate v-model:value="rating" />
    <span>{{ rating }} / 5</span>
  </n-space>
</template>
```

### 3. Use Readonly for Display

When displaying existing ratings, use `readonly` mode:

```vue
<template>
  <n-rate readonly :value="averageRating" allow-half />
</template>
```

### 4. Consider Clearable Option

Allow users to reset their rating when appropriate:

```vue
<template>
  <n-rate clearable v-model:value="rating" />
</template>
```

### 5. Use Custom Colors Wisely

Choose colors that match your design system and are accessible:

```vue
<template>
  <n-rate color="#18a058" v-model:value="rating" />
</template>
```

### 6. Match Size with Context

Use appropriate sizes based on the context:

```vue
<template>
  <n-space vertical>
    <n-rate size="small" v-model:value="compact" />
    <n-rate size="medium" v-model:value="standard" />
    <n-rate size="large" v-model:value="prominent" />
  </n-space>
</template>
```

### 7. Validate in Forms

Add validation rules when using in forms:

```javascript
const rules = {
  rating: {
    required: true,
    type: 'number',
    min: 1,
    message: 'Please provide a rating',
    trigger: 'change'
  }
}
```