Rate

17:06

Description

Rating component supporting tap and slide to rate. Configurable star count, size, gutter and selected/unselected colors, plus allow-half half stars and colors / icons for segment coloring by rating range. The selected star count is bound via v-model (model-value defaults to -1 as a sentinel) and change returns the current value.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Click a star to rate; clicking the first star clears the rating.

View source

<template>
    <ux-rate :model-value="value" @change="onChange" />
</template>

<script setup lang="uts">
const value = ref<number>(0);

const onChange = (val: number) => {
    value.value = val;
};
</script>

Count & Size

Set the number of stars via count and star size via size.

View source

<template>
    <ux-rate :count="8" :current="5" :size="22" />
</template>

Custom Colors

Customize selected/unselected colors via active-color / inactive-color.

View source

<template>
    <ux-rate :current="3" active-color="#ff9900" inactive-color="#c8c9cc" />
</template>

Half Star allow-half

When allow-half=true, tap the left half of a star to select half a star (0.5) or the right half for a full star; tapping the first star's half or full clears the rating.

View source

<template>
    <ux-rate :model-value="value" allow-half active-color="#fa3534" @change="onChange" />
</template>

<script setup lang="uts">
const value = ref<number>(3.5);

const onChange = (val: number) => {
    value.value = val;
};
</script>

Disabled State

When disabled=true the component is not interactive and only displays the rating.

View source

<template>
    <ux-rate :current="4" disabled />
</template>

Segmented Colors

Use the colors array to display different colors by rating range.

View source

<template>
    <ux-rate :model-value="value" :colors="colors" @change="onChange" />
</template>

<script setup lang="uts">
const value = ref<number>(3);
const colors: string[] = ['#2979ff', '#ff9900', '#fa3534'];

const onChange = (val: number) => {
    value.value = val;
};
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
modelValue	Number of selected stars, two-way bound via v-model	number | string	-1	-
count	Number of stars to display	number | string	5	-
current	Star count selected by default	number | string	0	-
disabled	Whether selection is disabled	boolean	false	-
size	Star size	number | string	16	-
inactiveColor	Color of unselected stars	string	''	-
activeColor	Color of selected stars	string	''	-
gutter	Gutter between stars	number | string	5	-
minCount	Minimum number of stars to select	number | string	0	-
allowHalf	Whether half stars are allowed	boolean	false	-
activeIcon	Icon of selected stars	string	'star-fill'	-
inactiveIcon	Icon of unselected stars	string	'star'	-
customPrefix	Custom icon prefix	string	'uicon'	-
colors	Segmented colors	string[]	-	-
icons	Segmented icons	string[]	-	-

Events

Event	Description	Params	Version
change	Fires when the selected stars change	value: number	-

Slots

ux-rate has no slots.

Notes

1. model-value defaults to -1 as a sentinel: only a non--1 value (or v-model) enables two-way binding and syncs update:modelValue on change; with current alone the component does not write back.
2. With allow-half, tapping a star's left half records 0.5 and the right half a full star; tapping the first star's full star (when already 1) or half star (when already 0.5) clears the rating.
3. Tap and slide (touchmove) are both supported; slide rating converts by the measured single-star width, and half-star detection depends on the initial layout measurement — remeasure after the container width changes.
4. min-count sets the minimum selectable stars; count sets the number of stars; disabled blocks both tap and slide.
5. colors / icons only take effect when the array length is no greater than count, picking color / icon by rating range; otherwise they fall back to active-color / active-icon.
6. Stars come from ux-icon; replace the icon names via active-icon / inactive-icon.
7. Inside ux-form-item, a rating change triggers form validation; the -1 placeholder (unrated) does not.